Como consultar um nome em um banco de dados usando um MCP Server e um Agent Component

Aprenda a criar uma pequena integração de ponta a ponta em que um Agent recebe um nome, chama uma ferramenta MCP e recupera o registro correspondente no banco de dados.

Neste caso de uso, você vai configurar um Agent para acionar uma ferramenta MCP e retornar um resumo baseado nos registros do banco de dados.

Você vai configurar:

• Uma ferramenta buscar-pessoas exposta por um pipeline MCP Server.

• Um pipeline Agent que aciona essa ferramenta automaticamente.

Para reproduzir este exemplo, você precisa de um banco de dados com uma tabela de pessoas e das credenciais adicionadas como uma Conta na Digibee.

Passo a passo

1

Expor o banco de dados como uma ferramenta MCP

O primeiro passo é criar um pipeline MCP Server que disponibilize sua consulta ao banco de dados como uma ferramenta. É isso que o Agent chamará depois.

Criar o pipeline MCP Server

Crie um pipeline chamado mcp-buscar-nome-bd (o nome deve ser único no seu realm; se ele já existir, escolha outro). Depois abra a configuração do trigger e selecione MCP Server como o tipo.

Dentro das configurações do trigger:

1. Clique em Adicionar Ferramenta para criar uma nova ferramenta.

2. Preencha os seguintes campos:

• Nome da Ferramenta: buscar-pessoas

• Descrição: "Busca de pessoas em um banco de dados"

• Você pode deixar os campos de schema em branco por agora.

1. Ative as opções de segurança:

• External API: Torna o pipeline acessível por uma URL pública.

• API Key: Garante que o endpoint exija autenticação.

Depois de salvar, o pipeline cria automaticamente dois caminhos que levam para conectores Block Execution:

• buscar-pessoas: Executado quando a ferramenta existe.

• Tool Not Found: Executado quando o Agent chama uma ferramenta inexistente.

Vamos configurar ambos.

2

Implementar a lógica da consulta ao banco de dados

O caminho buscar-pessoas é onde o trabalho real acontece. Aqui, conectamos ao banco de dados e executamos a consulta usando valores enviados pelo Agent.

Configurar o caminho buscar-pessoas

Passe o mouse sobre o conector Block Execution desse caminho e clique em OnProcess para definir o que acontece quando a ferramenta é executada.

Você verá um JSON Generator padrão. Remova-o e adicione um conector DB V2 configurado da seguinte forma:

Aba General

• Account: Selecione a conta do banco adicionada anteriormente na Plataforma.

Aba Operation

• Type: Query

• Database URL: Exemplo: jdbc:mysql://34.224.165.98/db-training

• SQL Statement: Exemplo:

select * from clientes where name = {{ message.arguments.name }}

Esse valor dinâmico vem da chamada da ferramenta. Quando o Agent invoca buscar-pessoas, ele envia um objeto como:

{
  "arguments": {
    "name": "João Souza"
  }
}

A expressão {{ message.arguments.name }} extrai esse valor e o usa diretamente na consulta SQL.

3

Fornecer uma mensagem clara quando o nome da ferramenta estiver incorreto

Abra o caminho Tool Not Found, passe o mouse sobre o Block Execution e clique em OnProcess. Dentro do fluxo, ajuste o conector Throw Error.

Você pode personalizar a mensagem, mas se deixar como padrão, o MCP Server retorna automaticamente:

• HTTP 404

• Message: Tool not found

Isso é útil para depuração caso a configuração do Agent faça referência a uma ferramenta incorreta.

4

Testar o pipeline MCP

Antes de conectá-lo ao Agent, faça um teste rápido no Painel de Execução.

Use:

{
  "tool": "buscar-pessoas",
  "arguments": {
    "name": "João Souza"
  }
}

Um resultado bem-sucedido conterá o registro consultado:

{
  "data": [
    {
      "uf": "RJ",
      "codigo": 7676,
      "cidade": "Rio de Janeiro",
      "logradouro": "Rua Visconde de Pirajá",
      "name": "João Souza",
      "due_date": 1724112000000,
      "created_at": 1718717592000,
      "email": "[email protected]",
      "cep": "22410-003"
    }
  ],
  "updateCount": 0,
  "rowCount": 1
}

Se aparecerem dados, a conexão com o banco, a chamada da ferramenta e a consulta SQL estão funcionando corretamente. Certifique-se de salvar o seu pipeline.

5

Proteger e fazer deploy do endpoint MCP

Criar uma Chave de API

Abra Configurações na Plataforma e vá até Consumers (Chaves de API). Você pode criar um novo consumer ou adicionar o pipeline mcp-buscar-nome-bd a um existente.

Copie a Chave de API gerada. O Agent vai usá-la depois.

Fazer o deploy do pipeline

Abra a página Run, procure o pipeline, crie e confirme a Implantação.

Após o deploy, abra os detalhes do pipeline e copie a URL pública do endpoint MCP (termina com /mcp). Você vai colá-la na ferramenta do Agent.

6

Registrar a conta do provedor de LLM

Antes de configurar seu Agent, registre a conta do provedor de LLM que será usada. Para isso:

1. Crie uma chave de API no seu provedor LLM (OpenAI no exemplo).

2. Na Plataforma, registre-a como uma conta do tipo Secret Key.

7

Criar o pipeline do Agent

Agora vamos criar a parte do fluxo que se comunica com o usuário. O Agent vai receber um nome, chamar a ferramenta MCP, recuperar os dados e resumi-los.

Configurar o pipeline

Crie um pipeline chamado api-buscar-pessoas-mcp (o nome deve ser único no seu realm; se ele já existir, escolha outro). Depois configure o trigger como REST e faça as seguintes alterações:

• Mantenha apenas o método GET ativo.

• Ative estas opções de segurança:

  • External API: Expõe o pipeline com uma URL pública.

  • API Key: Requer autenticação para acessar o endpoint.

Lembre-se de criar uma Chave de API para esse pipeline em Consumers (Chaves de API). Você pode reutilizar o consumer criado no passo 5.

Logo após o trigger, adicione um JSON Generator com:

{
  "arguments": {{ message.queryAndPath }}
}

Isso garante que todos os parâmetros de query e de path enviados na requisição GET sejam mapeados corretamente para um objeto JSON.

Depois, adicione o Agent Component.

8

Configurar o Agent Component

Dentro da configuração do Agent Component:

• Modelo: OpenAI – GPT-4.1 Mini (bom custo-benefício para este exemplo)

• Mensagem do Sistema:

Você é um assistente que pode consultar informações sobre pessoas em um banco de dados.
Você tem acesso a uma ferramenta chamada "buscar-pessoas", que recupera registros com base no nome da pessoa.
Quando alguém pedir informações sobre alguém, chame a ferramenta "buscar-pessoas" usando o nome correto como entrada.
Se a ferramenta retornar dados, resuma claramente os principais detalhes.

• Mensagem do Usuário:

Encontre informações sobre {{ message.arguments.name }} no banco de dados.

9

Adicionar a ferramenta ao Agent

Crie uma nova ferramenta no Agent:

• Nome: buscar-pessoas (deve ser o nome exato da ferramenta criada no MCP Server)

• URL do Servidor: Cole o endpoint MCP implantado, copiado no passo 5. Exemplo:

https://test.godigibee.io/pipeline/enablement/v1/mcp-buscar-nome-bd/mcp

• Cabeçalhos: Adicione um par de chave-valor e cole a API Key copiada no passo 5. Exemplo:

apikey: 7f3c1e9b4d2a47c8a1f0e6b29c5d803f

Com isso, o Agent já consegue acessar o endpoint MCP com segurança. Agora você pode salvar esse pipeline.

10

Executar o caso de uso ponta a ponta

Dentro do Painel de Execução

Para testar o fluxo dentro da Digibee, abra o Painel de Execução do pipeline api-buscar-pessoas-mcp e envie:

{
  "queryAndPath": {
    "name": "João Souza"
  }
}

Veja o que acontece nos bastidores:

1. O Agent lê o nome.

2. Ele decide chamar a ferramenta buscar-pessoas.

3. O pipeline MCP recebe a chamada da ferramenta e executa a consulta SQL.

4. O resultado é retornado ao Agent.

5. O Agent escreve um resumo simplificado em linguagem natural.

Exemplo:

{
  "body": {
    "text": "Encontrei informações sobre João Souza. Ele reside no Rio de Janeiro, especificamente na Rua Visconde de Pirajá, CEP 22410-003. Seu e-mail é [email protected]. Ele está registrado em nosso banco de dados desde a data UNIX 1718717592000 e tem uma data de vencimento registrada como 1724112000000."
  },
  "tokenUsage": {
    "inputTokenCount": 407,
    "outputTokenCount": 106,
    "totalTokenCount": 513
  }
}

Em uma ferramenta de testes de API

Para testar o caso de uso fora da Digibee, faça o deploy do pipeline api-buscar-pessoas-mcp (da mesma forma que você fez com mcp-buscar-nome-bd) e copie o endpoint.

Em seguida, siga estes passos:

1. Abra sua ferramenta de testes de API (por exemplo, Postman).

2. Selecione o método GET.

3. Cole o endpoint (por exemplo: https://test.godigibee.io/pipeline/enablement/v1/api-buscar-pessoas-mcp).

4. Em Params, adicione o seguinte par de chave–valor:

   • name: João Souza (substitua por uma informação disponível no seu banco de dados)

5. Em Headers, adicione o seguinte par de chave–valor:

   • apikey: 7f3c1e9b4d2a47c8a1f0e6b29c5d803f (substitua pela Chave de API criada para o pipeline api-buscar-pessoas-mcp)

6. Clique em Send.

Exemplo de resposta:

{
  "body": {
    "text": "Encontrei informações sobre João Souza. Ele reside no Rio de Janeiro, especificamente na Rua Visconde de Pirajá, CEP 22410-003. Seu e-mail é [email protected]. Ele está registrado em nosso banco de dados desde a data UNIX 1718717592000 e tem uma data de vencimento registrada como 1724112000000."
  },
    "tokenUsage": {
        "inputTokenCount": 353,
        "outputTokenCount": 118,
        "totalTokenCount": 471
    }
}

Configurações adicionais do Agent para melhorar a precisão

Depois que o seu Agent estiver funcionando, você pode aumentar a consistência ajustando parâmetros como temperatura, top-p, top-k e a validação opcional por Esquema JSON. Temperaturas mais baixas ajudam a reduzir alucinações, enquanto os esquemas garantem que o resultado sempre siga a estrutura esperada. Essas configurações são opcionais, mas recomendadas para cenários de produção.

Para explicações completas e detalhes sobre os parâmetros, consulte a documentação completa do Agent Component.