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

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:

Clique em Adicionar Ferramenta para criar uma nova ferramenta.
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.

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.

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.

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.

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.

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.

Registrar a conta do provedor de LLM

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

Crie uma chave de API no seu provedor LLM (OpenAI no exemplo).
Na Plataforma, registre-a como uma conta do tipo Secret Key.

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.

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.

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.

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:

O Agent lê o nome.
Ele decide chamar a ferramenta buscar-pessoas.
O pipeline MCP recebe a chamada da ferramenta e executa a consulta SQL.
O resultado é retornado ao Agent.
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:

Abra sua ferramenta de testes de API (por exemplo, Postman).
Selecione o método GET.
Cole o endpoint (por exemplo: https://test.godigibee.io/pipeline/enablement/v1/api-buscar-pessoas-mcp).
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)
Em Headers, adicione o seguinte par de chave–valor:
- apikey: 7f3c1e9b4d2a47c8a1f0e6b29c5d803f (substitua pela Chave de API criada para o pipeline api-buscar-pessoas-mcp)
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.

AnteriorCasos de Uso PróximoComo usar o Agent Component em cenários reais

Atualizado há 17 dias

Isto foi útil?