Adaptador MCP

Intenção

Expor sistemas internos como servidores MCP (Model Context Protocol), para que qualquer agente use o mesmo contrato de ferramentas. Serve para empresas com vários agentes, clientes e modelos que precisam acessar os mesmos sistemas.

Problema

Vitor trabalha no time de plataforma de uma empresa com quatro agentes em produção: suporte, back-office, engenharia e um assistente interno. Os quatro precisam consultar o ERP, o CRM e a base de tickets.

Cada time escreveu suas próprias ferramentas. O ERP tem quatro implementações de “buscar pedido”, com nomes, parâmetros e formatos de retorno diferentes. Uma devolve a data como 2026-09-30, outra como 30/09/2026, e uma terceira devolve o objeto inteiro do ERP, com 80 campos.

Quando a API do ERP mudou a autenticação, quatro times tiveram que corrigir o código na mesma semana. Quando a empresa quis testar um assistente de código que já sabe falar MCP, ninguém conseguiu ligar o ERP nele sem escrever a integração do zero.

E ninguém sabia responder uma pergunta simples da auditoria: quais agentes podem criar devoluções, e em nome de quem?

O problema não é cada ferramenta. É a falta de um contrato comum entre os sistemas e quem os usa.

A pergunta que este padrão responde: como escrever cada integração uma vez e usá-la em qualquer agente, modelo ou cliente?

Solução

Para cada sistema, crie um servidor MCP que expõe ferramentas (ações), recursos (dados para ler) e, quando fizer sentido, prompts prontos. O servidor é dono da autenticação, das permissões, da validação e do formato de saída. Os agentes se conectam como clientes MCP e recebem a lista de ferramentas com nome, descrição e schema.

O MCP é um protocolo aberto, lançado pela Anthropic em novembro de 2024 e adotado depois por outros provedores e ferramentas. O mesmo servidor funciona com agentes próprios, com assistentes de código, com IDEs e com conectores MCP das APIs de modelo. A integração deixa de pertencer a um agente e passa a pertencer ao sistema.

Pense na conta de integrações. Com 4 agentes e 3 sistemas, cada time escrevendo a sua, são até 12 integrações para manter. Com um servidor por sistema, são 3 servidores, e cada agente novo só precisa de um cliente MCP, que o framework normalmente já traz.

Exemplo trabalhado

O MCP usa mensagens JSON-RPC. Quando o agente de suporte conecta no servidor do ERP, o cliente pede a lista de ferramentas (tools/list) e recebe algo assim (resumido):

{
  "tools": [
    {
      "name": "find_order",
      "description": "Busca status, itens e datas de um pedido. Use quando o usuário citar um número de pedido.",
      "inputSchema": {
        "type": "object",
        "properties": { "order_id": { "type": "string", "pattern": "^[0-9]+$" } },
        "required": ["order_id"]
      }
    }
  ]
}

O cliente entrega essa lista ao modelo como definições de ferramenta. Quando o modelo decide usar find_order, o cliente manda um tools/call:

{ "method": "tools/call", "params": { "name": "find_order", "arguments": { "order_id": "88231" } } }

O servidor checa o escopo do usuário, chama o ERP e devolve só o que interessa:

{
  "content": [
    { "type": "text", "text": "{\"id\": \"88231\", \"status\": \"entregue\", \"delivered_at\": \"2026-09-30\", \"items\": [{\"sku\": \"CAD-112\", \"qty\": 2}]}" }
  ],
  "isError": false
}

Repare no que o agente não vê: a URL do ERP, o token de serviço, os 80 campos crus. Os quatro agentes recebem a mesma resposta, no mesmo formato, com a mesma data.

Estrutura

flowchart LR
  A1(["1. Agente de suporte"]):::llm --> C["2. Cliente MCP"]:::tool
  A2(["1. Agente de back-office"]):::llm --> C
  A3(["1. Assistente de código"]):::llm --> C
  C --> S1["3. Servidor MCP do ERP"]:::tool
  C --> S2["3. Servidor MCP do CRM"]:::tool
  S1 --> P{"4. Auth e permissões"}
  P --> ERP[("5. ERP")]:::store
  S2 --> CRM[("5. CRM")]:::store

1. Vários agentes, de times e tecnologias diferentes.
2. Cada um fala MCP por um cliente padrão.
3. Um servidor por sistema expõe ferramentas com schema e descrição.
4. O servidor aplica autenticação e permissões do usuário ou do agente, e valida as entradas.
5. Só o servidor fala com o sistema interno, e devolve dados normalizados.

Pseudocódigo

server erp_mcp:
    tool find_order(order_id: string) -> Order               # leitura
        require scope("orders:read")
        return normalize(erp.get_order(order_id))

    tool create_return(order_id: string, reason: string) -> ReturnLabel   # efeito
        require scope("returns:write")
        audit.log("create_return", caller, order_id)
        return erp.create_return(order_id, reason, idempotency_key=request_id())

    resource "erp://policies/returns" -> text                # dado para ler

agent support:
    tools = mcp.connect("erp_mcp", token=user_token).list_tools()      # 2
    run_agent(SUPPORT_PROMPT, tools)                                    # 1

Cenários reais

• Agente de código. Tracker de tarefas, CI e documentação interna são servidores MCP. O mesmo agente roda no terminal do desenvolvedor e na automação, com as mesmas ferramentas. O que muda: trocar de assistente de código não exige reescrever nenhuma integração.
• Automação de back-office com execução durável. Banco, ERP e emissor de notas viram servidores MCP com ferramentas de leitura e de efeito separadas, e cada processo conecta só nos que precisa. O que muda: o processo de conciliação recebe um token só com escopo de leitura.
• Chat com a base de conhecimento interna. A wiki e as pastas compartilhadas são expostas como recursos MCP, com o controle de acesso do próprio sistema. O que muda: a pessoa só vê no chat os documentos que já podia abrir na wiki.

Aplicabilidade

• Mais de um agente ou cliente usa o mesmo sistema.
• Você quer trocar de modelo, framework ou cliente sem reescrever integrações.
• Autenticação, permissões e auditoria precisam ser iguais para todos os agentes.
• Ferramentas de terceiros (IDEs, assistentes) devem acessar seus sistemas de forma controlada.

Quando não usar

• Um agente só, com duas ferramentas simples. Uma função local resolve com menos peças.
• Latência mínima é o requisito principal e cada milissegundo conta. Um servidor separado acrescenta um salto de rede.
• O sistema não tem dono claro para manter o servidor. Um servidor abandonado vira um ponto de falha compartilhado.

Como implementar

1. Escolha um sistema usado por vários agentes e liste as operações que eles realmente fazem.
2. Desenhe ferramentas por intenção, com nomes claros, descrições que dizem quando usar e schemas estritos.
3. Separe leitura de efeito, e exija escopos diferentes.
4. Normalize a saída: só os campos úteis, num formato estável.
5. Implemente autenticação que identifica quem está chamando (o usuário final, não só o agente).
6. Registre chamadas com efeito numa trilha de auditoria.
7. Publique o servidor, documente e migre um agente por vez, rodando o eval de cada um.
8. Versione o servidor e trate mudanças de schema como mudanças de API.

Armadilhas comuns

• Espelhar a API interna. Transformar cada endpoint do ERP numa ferramenta gera 60 ferramentas com nomes técnicos. O modelo precisa de operações por intenção: find_order, não GET /v2/sales/orders/{id}/header.
• Um token de serviço para tudo. Se o servidor chama o ERP sempre como “admin”, qualquer agente conectado pode tudo. Propague a identidade do usuário final e aplique o escopo dele.
• Devolver o objeto cru. Oitenta campos por resposta enchem o contexto e confundem o modelo. Veja Normalizar Saída da Ferramenta.
• Mudar o schema sem aviso. Renomear order_id para orderId num deploy quebra todos os agentes ao mesmo tempo. Acrescente campos; para remover ou renomear, publique uma versão nova.

Variações

• Servidor local (stdio). Roda como processo junto do agente. Simples para ferramentas de desenvolvedor.
• Servidor remoto (HTTP). Um serviço compartilhado, com autenticação e escala. O caminho para produção. A especificação do MCP define OAuth para autorizar clientes em servidores remotos.
• Conector MCP da API. O provedor do modelo conecta direto no servidor remoto, sem o seu código no meio do loop.
• Gateway MCP. Um ponto único que agrega vários servidores, aplica política comum e registra tudo.

Custo, latência e falhas

O custo de contexto é fácil de esquecer. Conectar três servidores com 20 ferramentas cada coloca 60 definições em toda chamada do agente. Exponha só o necessário por agente, ou combine com o Roteador de Ferramentas.

Como avaliar

• Eval de cada agente antes e depois de migrar para o servidor MCP: a qualidade não deve cair.
• Testes de contrato do servidor: entradas válidas e inválidas, permissões, formato de saída.
• Escolha de ferramenta: com a lista nova, o agente escolhe a ferramenta certa?

{ "agent": "support", "task": "status do pedido 88231", "expected_tool": "find_order", "expected_scope": "orders:read" }

Os testes de contrato não precisam de modelo. Chame o servidor direto, com um cliente MCP de teste: um order_id com letras deve ser recusado, um usuário sem returns:write não pode criar devolução, e a resposta de find_order tem sempre os mesmos campos. Esses testes rodam em todo deploy do servidor, antes de qualquer agente sentir a mudança.

Em produção

• Spans por chamada MCP com servidor, ferramenta, usuário, duração e erro.
• Painel por servidor: chamadas por agente, taxa de erro, latência.
• Alertas de disponibilidade por servidor, porque uma falha atinge vários agentes.
• Revisão periódica das ferramentas expostas: as que ninguém usa saem.

Segurança

O servidor MCP é a fronteira de segurança. Ele autentica quem chama, aplica o menor privilégio por ferramenta e nunca entrega credenciais ao modelo.

Servidores de terceiros são código de terceiros: revise antes de conectar. As descrições das ferramentas vão direto para o contexto do modelo, então uma descrição maliciosa funciona como prompt injection (injeção de instrução). Em 2025, pesquisadores da Invariant Labs demonstraram esse ataque com o nome de “tool poisoning”: instruções escondidas na descrição de uma ferramenta levavam o agente a vazar dados de outra.

Os retornos também são conteúdo não confiável. Uma issue pública, um e-mail ou uma página lida por uma ferramenta pode carregar instruções para o agente. Isso é a injeção indireta descrita por Greshake et al. (2023). Veja Instruções Não Confiáveis e Reduzir Permissões da Ferramenta.

Prós e contras

Relações

• Refatorações que chegam aqui: Expor Ferramenta via MCP e Normalizar Saída da Ferramenta.
• Vizinhos: Uso de Ferramentas é o mecanismo do modelo pedir uma ação; o Adaptador MCP decide onde essa ação mora e quem é dono dela. O Roteador de Ferramentas escolhe quais ferramentas dos servidores conectados o agente vê em cada tarefa.

Código

As duas abas criam um servidor MCP com uma ferramenta de leitura e uma de efeito, separadas por escopo.

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("erp")  # 3. um servidor por sistema


@mcp.tool()
def find_order(order_id: str) -> dict:
    """Busca status, itens e datas de um pedido. Use quando o usuário citar um número de pedido."""
    require_scope("orders:read")  # 4. permissão do usuário que chamou
    order = erp_client.get_order(order_id)
    return {  # 5. só campos úteis, formato estável
        "id": order.id,
        "status": order.status,
        "delivered_at": order.delivered_at.isoformat() if order.delivered_at else None,
        "items": [{"sku": i.sku, "qty": i.qty} for i in order.items],
    }


@mcp.tool()
def create_return(order_id: str, reason: str) -> dict:
    """Cria uma devolução para um pedido entregue. Só use depois de o cliente confirmar a devolução."""
    require_scope("returns:write")
    audit_log("create_return", order_id=order_id, reason=reason)
    label = erp_client.create_return(order_id, reason, idempotency_key=current_request_id())
    return {"return_id": label.id, "label_url": label.url}


@mcp.resource("erp://policies/returns")
def returns_policy() -> str:
    """Política de trocas e devoluções vigente."""
    return erp_client.get_policy("returns")


if __name__ == "__main__":
    mcp.run()  # stdio por padrão; para um servidor compartilhado, mcp.run(transport="streamable-http")

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "erp", version: "1.4.0" });

server.registerTool(
  "find_order",
  {
    description: "Busca status, itens e datas de um pedido. Use quando o usuário citar um número de pedido.",
    inputSchema: { order_id: z.string().regex(/^\d+$/) },
  },
  async ({ order_id }) => {
    requireScope("orders:read"); // 4
    const o = await erp.getOrder(order_id);
    const data = { id: o.id, status: o.status, delivered_at: o.deliveredAt, items: o.items.map((i) => ({ sku: i.sku, qty: i.qty })) };
    return { content: [{ type: "text", text: JSON.stringify(data) }] }; // 5
  },
);

server.registerTool(
  "create_return",
  {
    description: "Cria uma devolução para um pedido entregue. Só use depois de o cliente confirmar a devolução.",
    inputSchema: { order_id: z.string().regex(/^\d+$/), reason: z.string().max(500) },
  },
  async ({ order_id, reason }) => {
    requireScope("returns:write");
    await auditLog("create_return", { order_id, reason });
    const label = await erp.createReturn(order_id, reason, { idempotencyKey: currentRequestId() });
    return { content: [{ type: "text", text: JSON.stringify({ return_id: label.id, label_url: label.url }) }] };
  },
);

await server.connect(new StdioServerTransport());

Teste seu entendimento