MCP: conectar com segurança · Parte 2

Qual transporte usar

stdio

O cliente lança o servidor como subprocesso e troca mensagens por stdin e stdout, uma mensagem JSON-RPC por linha. Serve para ferramenta local: filesystem, git, banco de desenvolvimento.

Regra do protocolo: o servidor não pode escrever nada no stdout que não seja mensagem MCP. Logs vão para o stderr. Um print() esquecido no stdout quebra a conexão.

Streamable HTTP

Um único endpoint HTTP. Cada mensagem do cliente é um POST, e o servidor responde com JSON ou com um stream SSE. Serve para servidor hospedado ou compartilhado pelo time.

Na spec 2026-07-28, o protocolo não tem sessão: o servidor que precisa de estado entre chamadas devolve um identificador (um id de carrinho, por exemplo) e recebe esse id como argumento nas chamadas seguintes.

O transporte antigo HTTP+SSE está deprecado desde a spec 2025-03-26. Para servidor novo, use Streamable HTTP.

Autenticação

stdio

A spec manda o servidor stdio pegar credencial do ambiente, sem fluxo OAuth. No Claude Code: --env NOME=valor no claude mcp add.

HTTP: o fluxo OAuth em 3 passos

1. O cliente chama sem token. O servidor responde 401 com o header WWW-Authenticate apontando para os metadados do recurso.
2. O cliente descobre o servidor de autorização, abre o navegador e você aprova. O fluxo usa PKCE e o parâmetro resource com o endereço do servidor MCP.
3. Todo request leva Authorization: Bearer <token>. Token na query string é proibido pela spec.

Se faltar permissão no meio do uso, o servidor responde 403 com error="insufficient_scope" e o cliente pede o escopo adicional. Escopo mínimo no começo, mais permissão só quando a operação exigir.

O servidor também só pode aceitar tokens emitidos para ele mesmo. Repassar para a API de baixo um token recebido de outro serviço é proibido (token passthrough).

Configurar no Claude Code

Servidor remoto com OAuth:

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Depois, dentro de uma sessão, rode /mcp e siga o login no navegador. claude mcp login <nome> faz o mesmo pelo shell.

Servidor local com chave por variável de ambiente:

claude mcp add --env AIRTABLE_API_KEY=SUA_CHAVE --transport stdio airtable -- npx -y airtable-mcp-server

O -- separa as opções do Claude do comando do servidor.

Remoto com token fixo no header:

claude mcp add --transport http secure-api https://api.example.com/mcp --header "Authorization: Bearer seu-token"

Escopos

.mcp.json com variáveis

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

${VAR} lê a variável de ambiente e ${VAR:-padrão} usa o valor padrão se ela não existir. A chave fica fora do arquivo versionado.

Gerenciar

• claude mcp list: servidores e status (Connected, Needs authentication, Failed)
• claude mcp get <nome>: detalhes de um servidor
• claude mcp remove <nome>: remove
• /mcp na sessão: reconectar, autenticar, ou Clear authentication para revogar

Confiança e risco

Prompt injection por resultado de tool

Servidor que lê issue, e-mail ou página web devolve texto escrito por terceiros. Esse texto pode conter instruções dirigidas ao modelo. A doc do Claude Code avisa: conecte só servidores em que você confia e tenha cuidado com os que leem conteúdo não confiável.

A spec recomenda que o cliente mantenha uma pessoa no circuito, mostre os argumentos antes de chamar a tool e peça confirmação em operações sensíveis. Tool annotations só valem se vierem de servidor confiável.

Servidor local é código na sua máquina

Um servidor stdio roda com os privilégios do seu usuário. A própria spec cita o risco de um comando de inicialização como npx pacote && curl ... enviando arquivos para fora. Leia o comando inteiro antes de aceitar.

O Claude Code pede aprovação antes de usar servidores de um .mcp.json de repositório clonado.

Servidor HTTP em localhost

A spec manda o servidor validar o header Origin (responder 403 se for inválido, contra DNS rebinding) e escutar em 127.0.0.1, não em 0.0.0.0.

Checklist antes do claude mcp add

1. Li o comando inteiro, sem curl, sudo ou redirecionamento suspeito depois do npx
2. A origem é o repositório do fornecedor, com versão fixada
3. O acesso é o menor possível: pasta específica, token só de leitura, escopo mínimo
4. A aprovação de tool que escreve ou envia continua ligada
5. A chave está em variável de ambiente, fora do .mcp.json
6. Sei como revogar: /mcp e Clear authentication, ou claude mcp remove

@developer.israel · MCP · Parte 2 de 2