Domínio 2 — Tool Design & MCP Integration · Lição 5 de 6

MCP: arquitetura, transportes e configuração

Objetivos de aprendizagem

• Descrever a arquitetura cliente-servidor do Model Context Protocol e suas três primitivas: tools, resources e prompts.
• Diferenciar os transportes stdio (processo local) e HTTP (servidor remoto).
• Configurar servidores no Claude Code: .mcp.json de projeto (compartilhado no repositório) vs ~/.claude.json de usuário (pessoal/experimental), com expansão ${VAR} para credenciais.
• Entender a descoberta de tools na conexão e usar resources como catálogo para reduzir chamadas exploratórias.
• Decidir entre servidores comunitários e implementações custom; conhecer o MCP connector da API (beta).

Arquitetura cliente-servidor

O MCP padroniza como aplicações de IA (hosts) acessam contexto e ações externas. Um host (Claude Code, Claude Desktop, seu agente) mantém um cliente MCP por conexão; cada servidor MCP expõe capacidades de um sistema (GitHub, Jira, banco de dados) num protocolo único. Na conexão, o cliente faz o handshake e descobre as tools do servidor (tools/list); as tools de todos os servidores configurados ficam disponíveis simultaneamente para o agente.

flowchart LR
    subgraph Host [Host: Claude Code / agente]
      M[Modelo] --- C1[Cliente MCP 1]
      M --- C2[Cliente MCP 2]
    end
    C1 -- stdio --> S1[Servidor local\nex.: filesystem]
    C2 -- HTTP --> S2[Servidor remoto\nex.: GitHub]
    S1 --- P1[(tools / resources / prompts)]
    S2 --- P2[(tools / resources / prompts)]
  

As três primitivas

Transportes: stdio e HTTP

• stdio: o host lança o servidor como processo local filho e conversa por stdin/stdout. Ideal para servidores locais (filesystem, CLIs). Baixa latência, sem rede.
• HTTP (streamable): o servidor roda remoto e atende via HTTP. Ideal para serviços compartilhados/hospedados, com autenticação própria (tokens, OAuth).

Configuração no Claude Code

Dois escopos principais:

.mcp.json de projeto com expansão de variável de ambiente — o token não é commitado; cada dev define GITHUB_TOKEN no próprio ambiente:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      }
    },
    "local-db": {
      "command": "npx",
      "args": ["-y", "@example/db-mcp-server"],
      "env": {
        "DB_URL": "${DATABASE_URL}"
      }
    }
  }
}

Gerenciamento pela CLI com claude mcp:

# adicionar servidor stdio no escopo do projeto (.mcp.json)
claude mcp add --scope project local-db -- npx -y @example/db-mcp-server

# adicionar servidor pessoal (escopo de usuário)
claude mcp add --scope user experiments -- npx -y @example/experimental-server

# listar e remover
claude mcp list
claude mcp remove experiments

Comunitário vs custom: para integrações padrão (Jira, GitHub, Postgres), prefira servidores comunitários existentes — manutenção compartilhada e chegada mais rápida. Reserve servidores custom para workflows específicos do seu time que nenhum servidor pronto cobre.

MCP connector na API (beta)

Fora do Claude Code, a Messages API pode conectar-se diretamente a servidores MCP remotos via MCP connector (beta mcp-client-2025-11-20): a Anthropic faz a conexão server-side. Dois parâmetros obrigatórios juntos: mcp_servers (as conexões) e uma entrada mcp_toolset em tools referenciando cada servidor pelo name:

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=2048,
    betas=["mcp-client-2025-11-20"],
    mcp_servers=[{
        "type": "url",
        "url": "https://mcp.example.com/sse",
        "name": "issue-tracker",
        "authorization_token": "TOKEN_AQUI",
    }],
    tools=[{
        "type": "mcp_toolset",
        "mcp_server_name": "issue-tracker",
    }],
    messages=[{
        "role": "user",
        "content": "Liste as issues abertas com label 'bug' e resuma as 3 mais antigas.",
    }],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

Pegadinhas da prova

• Distrator típico: colocar o servidor do time em ~/.claude.json — os colegas não recebem; tooling compartilhado vai em .mcp.json versionado no projeto.
• Distrator típico: commitar o token literal no .mcp.json "porque o repo é privado". Use ${VAR}; segredo fica no ambiente de cada dev.
• Pegadinha: resources não são tools — são conteúdo que o host anexa; o padrão "catálogo como resource" existe justamente para evitar chamadas exploratórias de tools.
• Distrator típico: escrever um servidor Jira custom do zero quando há servidor comunitário maduro — custom é para workflow específico do time.
• Pegadinha: MCP connector na API é beta (mcp-client-2025-11-20) e exige mcp_servers + mcp_toolset juntos.

Resumo em 5 linhas

Documentação oficial

• Model Context Protocol — Introdução
• Claude Code — MCP
• Claude API — MCP connector

Questões de fixação