MCP — Model Context Protocol

5.1 O problema que o MCP resolve e a arquitetura

Sem um padrão, cada combinação de aplicação de IA com sistema externo exige uma integração própria: 5 assistentes e 10 sistemas são 50 integrações, cada uma com seu formato de ferramenta. O MCP é um protocolo aberto (lançado pela Anthropic em 2024 e adotado por boa parte do mercado) que transforma isso em 5 clientes + 10 servidores.

• Mensagens: JSON-RPC 2.0. O cliente faz initialize, descobre o que existe (tools/list, resources/list…) e chama (tools/call).
• Transporte stdio: o host inicia o servidor como subprocesso e conversa por stdin/stdout. Para ferramentas locais.
• Transporte Streamable HTTP: o servidor é um serviço web com um endpoint (/mcp). Para servidores remotos e compartilhados.

MCP ou ferramentas próprias?

5.2 As primitivas: ferramentas, recursos e prompts

Anotações de ferramentas

Ferramentas podem declarar dicas para o cliente: readOnlyHint (só lê), destructiveHint (pode destruir algo), idempotentHint (repetir é seguro), openWorldHint (fala com o mundo externo). Clientes usam isso para pedir confirmação antes de ações perigosas. São dicas: um servidor malicioso pode mentir, então elas nunca substituem as permissões no servidor.

Outras capacidades do protocolo

• Saída estruturada (outputSchema + structuredContent): o resultado vem como texto para o modelo e como JSON tipado para o código.
• Elicitation: o servidor pede um dado ao usuário no meio da operação ("qual dos 3 clientes chamados João?").
• Sampling: o servidor pede ao cliente que faça uma chamada ao LLM em seu nome, sem ter a própria chave.
• Notificações de progresso e logs, para operações longas.

5.3 Seu primeiro servidor MCP, em Python

As ferramentas da loja do Módulo 2, agora como servidor MCP:

from mcp.server import MCPServer
from mcp.server.mcpserver.exceptions import ToolError
from mcp.types import ToolAnnotations

loja = MCPServer(name="loja-exemplo")

@loja.tool(annotations=ToolAnnotations(read_only_hint=True))
def calcular_frete(cep: str, peso_kg: float) -> dict:
    """Calcula valor (em reais) e prazo (em dias úteis) de frete para um CEP e um peso em kg."""
    digitos = "".join(c for c in cep if c.isdigit())
    if len(digitos) != 8:
        raise ToolError("CEP deve ter 8 dígitos")   # erro previsto: a mensagem chega ao modelo
    ...

@loja.resource("loja://politicas/trocas", mime_type="text/markdown")
def politica_de_trocas() -> str: ...

@loja.prompt(title="Responder reclamação")
def responder_reclamacao(numero_pedido: str, reclamacao: str) -> str: ...

loja.run()   # stdio

A docstring vira a descrição que o modelo lê, e os tipos viram o JSON Schema dos parâmetros. Repare no ToolError: erros previstos chegam ao cliente com a mensagem, para o modelo se corrigir. Qualquer outra exceção vira uma mensagem genérica, para não vazar detalhes internos (caminhos, SQL, stack traces).

cd python
python cliente_loja.py          # inicia o servidor por stdio e explora tudo
python test_servidor_loja.py    # testa o servidor em memória
npx @modelcontextprotocol/inspector python servidor_loja.py   # interface web para explorar

FERRAMENTAS
  • consultar_pedido
    Busca um pedido pelo número. Devolve cliente, quantidade de itens, peso total em kg e status.
  • calcular_frete
  • cancelar_pedido  ⚠ destrutiva
RECURSOS
  • loja://politicas/trocas  (text/markdown)
  • loja://pedidos/{numero}  (modelo)
CHAMADAS
  consultar_pedido(4821) → {"cliente": "Ana Souza", "itens": 3, "peso_kg": 2.4, "status": "separando"}
  calcular_frete(...)    → {"regiao": "MG", "valor_reais": 44.6, "prazo_dias": 6}
  consultar_pedido(9999) → erro=True: Error executing tool consultar_pedido: Pedido 9999 não encontrado

5.4 Servidor MCP em TypeScript: o RAG vira serviço

No projeto, o RAG do Módulo 4 ganha uma porta MCP sem que uma linha dele seja reescrita. O servidor expõe três ferramentas, um modelo de recurso e um prompt:

servidor.registerTool(
  "buscar_documentacao",
  {
    description: "Busca trechos da documentação da Brisa relevantes para uma pergunta...",
    inputSchema: {
      pergunta: z.string().min(3).describe("A dúvida do cliente"),
      k: z.number().int().min(1).max(10).default(5),
    },
    outputSchema: { resultados: z.array(z.object({ id: z.string(), texto: z.string(), /* ... */ })) },
    annotations: { readOnlyHint: true },
  },
  async ({ pergunta, k }) => {
    const achados = await buscar(indice.banco, indice.embedder, pergunta, "hibrida", k);
    return {
      content: [{ type: "text", text: /* trechos com [id] */ }],   // para o modelo
      structuredContent: { resultados: /* ... */ },                // para código
    };
  },
);

servidor.registerResource("documento", new ResourceTemplate("docs://{documento}", { list: ... }), ...);
servidor.registerPrompt("atendimento", { argsSchema: { pergunta: z.string() } }, ...);

Boas práticas de design de servidor

• Ferramentas no nível da tarefa, não da tabela. buscar_documentacao é melhor que select_from_trechos. O modelo pensa em tarefas.
• Poucas ferramentas, bem descritas. Cada ferramenta ocupa contexto e compete pela escolha do modelo.
• Limites nos parâmetros (max(10)): o schema é a primeira barreira contra uso abusivo.
• Erros que ensinam: "Seção entregas#prazo não existe. Ids parecidos: entregas#prazos-de-entrega" permite ao modelo se corrigir sozinho.
• Resultados enxutos: devolva o necessário. 10 mil linhas de JSON poluem o contexto (Módulo 2, aula 2.3).
• No stdio, nunca escreva no stdout. Ele é o canal do protocolo; um console.log corrompe a comunicação. Use console.error.

Testando em memória

const [ladoCliente, ladoServidor] = InMemoryTransport.createLinkedPair();
await criarServidor(indice).connect(ladoServidor);
const cliente = new Client({ name: "teste", version: "0" });
await cliente.connect(ladoCliente);

const r = await cliente.callTool({ name: "ler_secao", arguments: { id: "entregas#prazo" } });
assert.equal(r.isError, true);

5.5 Consumindo MCP: hosts prontos, a API e o seu agente

Em hosts prontos

# Claude Code, servidor local (stdio)
claude mcp add documentacao-brisa -- npx tsx /caminho/modulo-05/projeto/src/stdio.ts

# Claude Code, servidor remoto (HTTP) com token
claude mcp add --transport http documentacao-brisa http://localhost:3333/mcp \
  --header "Authorization: Bearer $TOKEN"

{
  "mcpServers": {
    "documentacao-brisa": {
      "command": "npx",
      "args": ["tsx", "/caminho/modulo-05/projeto/src/stdio.ts"]
    }
  }
}

A sintaxe exata muda entre versões: confira a documentação do host que você usa.

Pela Messages API (servidor remoto)

Se o servidor estiver acessível pela internet, a própria API pode se conectar a ele, sem loop de ferramentas no seu código:

client.beta.messages.create(
    model="claude-opus-5-5", max_tokens=4000,
    betas=["mcp-client-2025-11-20"],
    mcp_servers=[{"type": "url", "url": "https://mcp.suaempresa.com/mcp",
                  "name": "docs", "authorization_token": TOKEN}],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "docs"}],
    messages=[{"role": "user", "content": "Qual o prazo para o interior de MG?"}],
)

No seu próprio agente

O src/assistente.ts do projeto inicia o servidor por stdio, lista as ferramentas, converte cada uma para o formato da API e faz o loop de tool calling do Módulo 2, mandando cada chamada para o servidor MCP. O assistente não sabe nada de RAG, só de protocolo: trocar o servidor por outro não muda uma linha dele.

const { tools } = await mcp.listTools();
const ferramentas = tools.map((f) => ({ name: f.name, description: f.description, input_schema: f.inputSchema }));
// ... loop: quando o modelo pede uma ferramenta:
const r = await mcp.callTool({ name: bloco.name, arguments: bloco.input });

5.6 Expondo serviços internos com segurança

Um servidor MCP na rede é uma API, e quem a chama é um agente que pode entrar em loop, ser manipulado ou simplesmente errar. O src/http.ts do projeto aplica as proteções em camadas, nesta ordem:

1. Escuta só em localhost por padrão. Expor para a rede é uma decisão explícita.
2. Autenticação antes de qualquer trabalho: token no cabeçalho Authorization: Bearer, comparado em tempo constante e guardado só como hash.
3. Limite de taxa por cliente (balde de fichas): um agente em loop recebe 429 com Retry-After, em vez de derrubar o serviço ou estourar o orçamento.
4. Limite de tamanho do corpo (64 KB).
5. Modo sem sessão (stateless): um servidor novo por requisição, sem estado entre clientes, fácil de escalar horizontalmente.
6. Identidade propagada: o id do cliente chega às ferramentas (extra.authInfo), o que permite filtrar dados por cliente.
7. Auditoria em JSON Lines: quem, qual ferramenta, quais argumentos, sucesso ou falha, quanto tempo.

MCP_TOKENS="$(openssl rand -hex 24):time-suporte" npm run servidor:http
curl -X POST localhost:3333/mcp           # → 401 Não autorizado

Em produção

• OAuth 2.1: a especificação do MCP define como servidores remotos se integram a um servidor de autorização (descoberta, escopos, tokens de curta duração). Tokens fixos, como no projeto, servem para serviços internos e para aprender.
• Escopos e menor privilégio: a credencial do servidor no sistema de destino deve poder fazer só o que as ferramentas precisam. Um servidor de consulta usa usuário de banco só de leitura.
• HTTPS e WAF/gateway na frente, como qualquer API pública.
• Dados por usuário: se cada usuário só pode ver os próprios pedidos, isso é checado no servidor com a identidade autenticada, nunca confiando em um cliente_id que o modelo passou como argumento.

5.7 Ataques específicos de MCP e como se defender

python verificar_servidor.py servidor_envenenado.py
python verificar_servidor.py servidor_loja.py

ℹ enviar_email: ação com efeito externo; exigir confirmação humana no cliente

⚠ 3 sinais de alerta:
  - descrição de converter: marcação que imita instrução de sistema
  - descrição de converter: pede para esconder algo do usuário
  - descrição de converter: menciona segredos ou credenciais

Projeto do módulo: a documentação da Brisa como servidor MCP

cd projeto
npm install
npm test                       # 19 testes, offline: em memória, HTTP real, proteções, assistente com API falsa

npm run servidor:stdio         # para Claude Code, Desktop, IDEs
npm run inspetor               # explorar no MCP Inspector
MCP_TOKENS="$(openssl rand -hex 24):eu" npm run servidor:http
npm run assistente -- "Posso pausar a assinatura durante uma viagem?"

Arquitetura

Entregáveis

1. Conecte o servidor ao Claude Code (ou outro host) e faça 5 perguntas reais. Registre quais ferramentas o modelo escolheu.
2. Adicione escopos: um token com docs:ler e outro com docs:admin, e uma ferramenta reindexar disponível só para o segundo.
3. Adicione uma ferramenta que exige confirmação humana (por exemplo, abrir_chamado_suporte, que usa elicitation ou devolve um pedido de confirmação).
4. Rode o verificar_servidor.py adaptado contra o seu servidor e corrija o que aparecer.
5. Escreva um README de segurança: o que o servidor pode fazer, com que credenciais, o que é auditado e como revogar um token.

Critérios de avaliação

Recursos para aprofundar

• modelcontextprotocol.io · especificação, conceitos e lista de SDKs
• SDK TypeScript e SDK Python · exemplos oficiais e guia de migração da v2 do Python
• MCP Inspector · ferramenta visual para testar servidores
• Servidores de referência · implementações para estudar
• Simon Willison — The lethal trifecta · o modelo mental de risco para agentes com ferramentas