Playbook: MCP na Prática: Conecte um Agente a uma Ferramenta Interna

Antes do MCP, integrar uma ferramenta a um agente era um problema de três camadas resolvido de forma artesanal em cada projeto: você precisava (1) serializar a chamada no formato que o modelo esperava, (2) executar a lógica da ferramenta, e (3) devolver o resultado em um formato que o modelo conseguia interpretar. Cada LLM tinha seu próprio dialeto de function calling. Trocar de modelo significava reescrever os adaptadores. Adicionar uma ferramenta nova significava tocar no código do agente.

O MCP inverte a dependência. Em vez de o agente saber como chamar cada ferramenta, o servidor MCP anuncia o que ele sabe fazer, e o agente descobre em tempo de execução via tools/list. O contrato é simples: cada tool tem um name, uma description (texto livre, lido pelo modelo), e um inputSchema (JSON Schema). O agente chama tools/call com o nome e os argumentos; o servidor executa e devolve o resultado. JSON-RPC 2.0 sobre stdio ou HTTP+SSE.

A analogia que uso: pense no servidor MCP como um microserviço com contrato autodescritivo. O cliente não precisa de documentação externa, o próprio servidor declara suas capacidades. Isso é o que permite um agente genérico (Claude, GPT-4, um modelo no Bedrock) consumir qualquer ferramenta sem recompilação. O protocolo faz o trabalho de tradução.

Um detalhe que muda tudo na prática: o agente escolhe qual tool chamar baseado na descrição, não no nome. O modelo lê o campo description como parte do contexto e decide se aquela tool resolve o que o usuário pediu. Isso significa que uma descrição ruim, vaga, técnica demais, sem exemplos de quando usar, vai fazer o agente ignorar a tool ou chamá-la no momento errado. Trate a descrição como um fragmento de prompt de sistema, não como um docstring.

Quando o agente recebe a lista de tools disponíveis via tools/list, o modelo vê algo assim no contexto:

{
  "name": "search_internal_knowledge_base",
  "description": "Busca documentos na base de conhecimento interna da empresa. Use quando o usuário fizer perguntas sobre políticas internas, processos de RH, documentação técnica de produtos ou histórico de projetos. NÃO use para perguntas sobre dados em tempo real ou informações externas à empresa.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": { "type": "string", "description": "Texto da busca em linguagem natural" },
      "department": { "type": "string", "enum": ["engineering", "hr", "finance", "all"], "default": "all" }
    },
    "required": ["query"]
  }
}

O modelo lê o campo description como instrução. Três elementos fazem uma descrição eficaz:

1. Quando usar (positivo): descreva o caso de uso em linguagem natural, próxima à forma como o usuário vai perguntar. "Use quando o usuário fizer perguntas sobre políticas internas" é melhor que "busca na KB".

2. Quando NÃO usar (negativo): isso reduz falsos positivos, o agente chamando a tool em contextos errados. Explicitar o escopo negativo é tão importante quanto o positivo.

3. Descrições dos parâmetros no inputSchema: cada campo description dentro do schema também é lido pelo modelo. "Texto da busca em linguagem natural" instrui o modelo a não mandar um ID técnico onde deveria mandar uma frase.

Um erro comum: copiar o nome da função como descrição. "description": "search_kb" é inútil, o modelo já tem o nome. A descrição precisa adicionar contexto semântico que o nome não carrega.

Outro erro: descrições genéricas demais. Se você tem três tools de busca e todas dizem "busca informações", o agente vai escolher aleatoriamente ou sempre usar a primeira. Diferencie com precisão.

Uma tool MCP não é um endpoint de API qualquer. É uma capacidade que um modelo de linguagem pode acionar autonomamente, baseado em sua interpretação de uma instrução em linguagem natural. Isso muda o modelo de ameaça fundamentalmente.

Em uma API tradicional, o chamador é um sistema determinístico que você controla. Em um agente com tools MCP, o chamador é um modelo que interpreta linguagem natural, e linguagem natural pode ser manipulada. Prompt injection é o ataque mais direto: um documento malicioso na base de conhecimento contém instruções para o modelo chamar uma tool com argumentos específicos. Se a tool tem poder demais, o dano é real.

Três princípios que aplico em qualquer integração MCP antes de ir para produção:

1. Mínimo privilégio no servidor, não no agente. Não adianta restringir o agente se o servidor MCP tem acesso de escrita ao banco inteiro. A identidade que executa o servidor MCP deve ter apenas as permissões que as tools expostas precisam, e nada mais. Na AWS, isso significa uma role IAM com política inline específica, não AdministratorAccess.

2. Allowlist explícita de tools por agente. Um servidor MCP pode expor 20 tools. Um agente específico pode precisar de 3. Não exponha todas, configure o cliente para filtrar tools/list e apresentar ao modelo apenas as tools relevantes para o contexto. Isso reduz a superfície de ataque e melhora a qualidade das escolhas do modelo.

3. Validação no servidor é mandatória, não opcional. O JSON Schema no contrato MCP é uma descrição para o modelo, não uma barreira de segurança. O modelo pode gerar argumentos que passam no schema mas são semanticamente inválidos ou maliciosos (path traversal em um campo de arquivo, SQL injection em um campo de query). Valide no handler, antes de executar qualquer operação com side effects.

O Bedrock AgentCore Gateway adiciona uma camada de controle gerenciada: autenticação OAuth 2.1 ou IAM, logging centralizado, e a capacidade de revogar acesso a uma tool específica sem mudar o código do agente. Para ambientes corporativos com requisitos de auditoria, essa camada vale o custo adicional.