MCP na prática: conectando o Claude Code

Conecte um servidor MCP quando você se pegar copiando dado de outra ferramenta para dentro do chat. É o critério da documentação oficial, e é o melhor que existe.

O resto deste guia é sobre as três decisões que vêm depois: qual transporte usar, em qual escopo instalar, e o que acontece quando o mesmo servidor aparece em dois lugares. As três têm respostas documentadas e contraintuitivas.

MCP resolve o que não tem CLI decente. Para o que tem, o CLI é mais eficiente em contexto.

A orientação oficial de custo é direta: prefira ferramentas de linha de comando quando existirem, porque elas não adicionam listagem por ferramenta — o agente simplesmente roda o comando. gh, aws, gcloud e sentry-cli entram nessa categoria.

O que sobra para MCP é o que não tem CLI, ou tem um ruim: Figma, Notion, banco de dados interno, API proprietária, ferramenta de monitoramento com dashboard mas sem terminal.

A lista de casos que a documentação usa como exemplo dá o tom: implementar feature descrita num ticket do Jira e abrir o PR, cruzar dado de Sentry com uso de feature, consultar banco de dados para achar usuários específicos, atualizar template a partir de design no Figma.

O padrão comum: dado que hoje você copia e cola.

Os cinco andares de um setup que aguenta produção colocam MCP na terceira camada, depois de contexto e capacidade — e essa ordem importa, porque servidor MCP em cima de CLAUDE.md ruim só enche o contexto.

O WebSocket tem duas limitações que decidem por você: não suporta OAuth e não é aceito pela flag --transport. Autenticação ali é só por header. Use HTTP a menos que o servidor precise mesmo empurrar evento.

Para servidor local, existe uma pegadinha de sintaxe que quebra na primeira tentativa:

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

O -- separa as opções do Claude Code do comando que roda o servidor. Sem ele, uma flag do seu servidor (--port, por exemplo) seria interpretada como opção do Claude Code.

E há um detalhe do --env que gera erro confuso: se o nome do servidor vier logo depois do --env, a CLI lê o nome como mais um par CHAVE=valor e rejeita. Coloque pelo menos outra opção entre os dois, como no exemplo acima.

Servidor stdio recebe CLAUDE_PROJECT_DIR no ambiente, apontando para a raiz do projeto. Isso permite resolver caminho relativo sem depender do diretório de trabalho.

Leia a última coluna de novo. O escopo "local" do MCP guarda no ~/.claude.json, na sua pasta pessoal — não no .claude/settings.local.json do projeto, que é onde vivem as configurações "local" de todo o resto do Claude Code.

A própria documentação sinaliza a divergência. É o tipo de coisa que custa meia hora: você procura o servidor no .claude/settings.local.json, não acha, e conclui que não instalou.

O que muda na prática:

Local é o padrão e serve para servidor experimental ou com credencial que você não quer versionar. Ele fica registrado dentro da entrada daquele projeto no ~/.claude.json, então não vaza para os seus outros projetos.

Projeto é o que o time compartilha. Gera .mcp.json na raiz, que você versiona.

Usuário vale em todos os seus projetos e continua privado.

claude mcp add --transport http stripe https://mcp.stripe.com                    # local
claude mcp add --transport http compartilhado --scope project https://exemplo/mcp  # projeto
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic  # usuário

Quando o mesmo servidor aparece em mais de um lugar, o Claude Code conecta uma vez só, usando a definição de maior precedência:

1. Local
2. Projeto
3. Usuário
4. Servidor de plugin
5. Conector do claude.ai

Duas regras dessa lista importam mais que a ordem.

Os campos não se mesclam. O entry inteiro do escopo vencedor é usado. Se o seu .mcp.json de projeto define URL e headers, e você tem um servidor local de mesmo nome com só a URL, o local vence inteiro — os headers do projeto não são herdados. Essa é a origem de "por que o servidor está sem autenticação se eu configurei header?".

Os critérios de duplicata mudam conforme a fonte. Os três escopos casam por nome. Plugins e conectores casam por endpoint: um plugin que aponte para a mesma URL ou comando de um servidor acima é tratado como duplicata, mesmo com nome diferente.

É o que torna um .mcp.json versionado viável: o arquivo vai para o repositório sem a chave de API dentro.

Duas sintaxes:

• ${VAR} — expande para o valor da variável
• ${VAR:-padrao} — expande para a variável, ou para o padrão se ela não existir

A expansão funciona em command, args, env, url e headers:

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

O comportamento quando a variável não existe é o detalhe que vale saber: o config carrega assim mesmo. O Claude Code reporta um aviso de variável faltando no claude mcp list e usa o texto ${VAR} literalmente, sem expandir. O servidor sobe com um header de autorização que diz literalmente Bearer ${API_KEY}, e a falha aparece só na primeira chamada.

Por isso vale usar :-padrao sempre que houver um fallback razoável.

Há uma exceção que confunde: o CLAUDE_PROJECT_DIR é setado no ambiente do servidor, não no do Claude Code. Referenciá-lo num .mcp.json exige default — ${CLAUDE_PROJECT_DIR:-.}. Só configuração vinda de plugin substitui a variável direto.

Servidor vindo de .mcp.json pede aprovação em sessão interativa, por segurança. claude mcp reset-project-choices limpa as escolhas.

Mas o prompt não existe em toda sessão. A documentação lista onde ele não aparece:

• execuções com claude -p
• sessões do Agent SDK
• sessões na nuvem
• sessão em bypassPermissions com skipDangerousModePermissionPrompt

Nesses contextos, o servidor de projeto é carregado sem perguntar.

Isso importa quando você clona repositório de terceiro e roda um comando não interativo dentro dele. O .mcp.json versionado sobe junto, e nada te consulta.

Para bloquear em qualquer modo, o caminho é disabledMcpjsonServers nas configurações. Também dá para excluir configurações de projeto inteiras com --setting-sources.

Vale saber que a confiança de workspace protege parte disso: um repositório clonado não consegue aprovar os próprios servidores. Aprovações commitadas no .claude/settings.json do projeto são ignoradas em pasta não confiável, e o servidor fica em ⏸ Pending approval em vez de conectar.

A recomendação que sai daí é simples: leia o .mcp.json antes de rodar Claude Code num repositório que não é seu, com o mesmo cuidado que você daria a um script de build.

Esta é a mudança que altera a economia de instalar MCP.

Com o tool search, ligado por padrão, as definições de ferramenta são adiadas em vez de carregadas no início. Só os nomes das ferramentas e as instruções do servidor entram no contexto inicial. O agente usa uma ferramenta de busca para descobrir o que precisa, e só o que ele usa entra no contexto.

O efeito: adicionar mais servidores MCP tem impacto mínimo na janela. A documentação afirma que não existe limite fixo de ferramentas por servidor — o limite prático é o seu orçamento de contexto.

Dá para controlar pelo ENABLE_TOOL_SEARCH:

Duas restrições valem conhecer. O tool search exige modelo com suporte a blocos tool_reference — Sonnet 4.5, Haiku 4.5, Opus 4.5 e posteriores. E ele é desligado automaticamente quando ANTHROPIC_BASE_URL aponta para host que não é de primeira parte, porque a maioria dos proxies não repassa esses blocos.

Para quem escreve servidor MCP, o campo de instruções do servidor ficou mais importante: é por ele que o agente decide buscar as suas ferramentas — mesma lógica de uma description de skill. E há um teto: descrições de ferramenta e instruções de servidor são truncadas em 2 KB cada. Coloque o essencial no começo.

A maioria dos servidores remotos exige login. O Claude Code trata isso com OAuth 2.0, e o fluxo é curto:

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

O claude mcp login roda o fluxo direto do shell, sem precisar abrir o painel /mcp dentro de uma sessão. Para limpar as credenciais depois, claude mcp logout <nome>.

O comportamento automático cobre bem o caso normal. Quando uma requisição a um servidor no qual você já entrou volta 401, o Claude Code renova o token, reconecta e tenta de novo uma vez — e só sinaliza o servidor no /mcp se a nova tentativa também falhar. Se o servidor rejeitar o refresh token, aparece um aviso apontando para /mcp, com a opção de reautenticar antes que a próxima chamada quebre.

Onde isso não funciona: modo não interativo. Não existe painel /mcp num claude -p ou numa sessão do Agent SDK, então o fluxo de OAuth não roda ali. O comportamento atual é razoável — o Claude Code avisa ao agente que as ferramentas daquele servidor estão indisponíveis até você autorizar, e o agente consegue dizer qual servidor precisa de login em vez de responder como se ele não existisse. Mas a autorização em si tem que sair de uma sessão interativa.

Uma armadilha de configuração: se você definiu headers.Authorization manualmente e o servidor rejeita esse header, o Claude Code reporta falha de conexão em vez de cair para OAuth. Se a intenção era usar OAuth, remova o header.

Servidor MCP pode expor resources, e você referencia com @, do mesmo jeito que referencia arquivo.

Digitar @ no prompt lista os resources de todos os servidores conectados, misturados aos arquivos no autocompletar. O formato é @servidor:protocolo://caminho:

Analise @github:issue://123 e sugira uma correção
Compare @postgres:schema://users com @docs:file://database/user-model

O resource é buscado e anexado automaticamente quando referenciado, e o caminho é pesquisável por busca aproximada no autocompletar.

Isso resolve um caso que ferramenta não resolve bem: quando você sabe exatamente qual dado quer e não quer que o agente gaste turnos descobrindo. Em vez de pedir "procure a issue 123 no GitHub" e esperar duas chamadas de ferramenta, você cola a referência e o conteúdo chega junto com o prompt.

O diretório de ferramentas de IA reúne as que valem conectar por MCP e as que já têm CLI melhor.

Servidor MCP que devolve muito texto envenena o contexto rápido. Existem três números para conhecer:

export MAX_MCP_OUTPUT_TOKENS=50000
claude

Quem escreve servidor tem uma alternativa melhor que pedir ao usuário para subir a variável: declarar _meta["anthropic/maxResultSizeChars"] na resposta de tools/list da ferramenta específica. Serve para saída inerentemente grande e necessária, como esquema de banco ou árvore de arquivos completa.

{
  "name": "get_schema",
  "description": "Retorna o esquema completo do banco",
  "_meta": { "anthropic/maxResultSizeChars": 200000 }
}

Sem a anotação, resultado acima do limite é persistido em disco e substituído por uma referência de arquivo na conversa — o que costuma ser o comportamento certo, mas surpreende quem esperava o conteúdo inline.

Uma ressalva: a anotação vale só para conteúdo de texto. Ferramenta que devolve imagem continua sujeita ao MAX_MCP_OUTPUT_TOKENS.

Um remoto, para o time, versionado com a chave fora do arquivo:

claude mcp add --transport http linear --scope project https://mcp.linear.app/mcp

O .mcp.json gerado vai para o repositório. Se precisar de header, use expansão de variável e documente a variável no README.

Um local, só seu, para uma ferramenta sem CLI:

claude mcp add --env NOTION_TOKEN=seu_token --transport stdio notion \
  -- npx -y @notionhq/notion-mcp-server

Depois de instalar, três comandos fecham o ciclo:

• claude mcp list — o que está configurado e o estado de cada um
• /mcp na sessão — o que está conectado, com opção de desligar
• /context — quanto de contexto os servidores estão ocupando

O último é o que evita acúmulo. Revise essa lista com a mesma frequência com que você revisa dependência de package.json.

Boa parte dos servidores MCP hoje chega empacotada como plugin, o que muda o que você precisa conferir antes. O critério está em plugins e marketplaces: como avaliar antes de instalar.

MCP ou CLI, quando existem os dois?

CLI. A orientação oficial de custo é explícita: ferramenta de linha de comando é mais eficiente em contexto porque não adiciona listagem por ferramenta. Reserve MCP para o que não tem CLI decente.

Instalei o servidor mas o Claude não usa as ferramentas dele.

Com o tool search ligado, o agente busca a ferramenta quando a tarefa pede. Se ele nunca busca, provavelmente as instruções do servidor não descrevem bem quando ele é útil — e elas são truncadas em 2 KB, então o essencial precisa vir primeiro. Rode /mcp para confirmar que o servidor está conectado.

Configurei header no .mcp.json e ele não é aplicado. Por quê?

Provavelmente existe um servidor de mesmo nome em escopo local, que tem precedência. E os campos não se mesclam: o entry local vence inteiro, sem herdar os headers do projeto. Confirme com claude mcp get <nome>.

É seguro rodar Claude Code num repositório com .mcp.json de terceiro?

Com cautela. Em sessão interativa você recebe prompt de aprovação, e repositório clonado não consegue aprovar os próprios servidores. Mas em claude -p, no Agent SDK e em sessão na nuvem esse prompt não existe. Leia o .mcp.json antes, ou use disabledMcpjsonServers.

• Anthropic — Claude Code Docs: Connect Claude Code to tools via MCP. Acesso em 20/08/2026.
• Anthropic — Claude Code Docs: Manage costs effectively. Acesso em 19/08/2026.
• Anthropic — Claude Code Docs: Extend Claude with skills. Acesso em 19/08/2026.
• Anthropic — Claude Code Docs: Settings. Acesso em 20/08/2026.
• Anthropic — Claude Code Docs: Sub-agents. Acesso em 20/08/2026.

Verificado em 20 de agosto de 2026.

Gatilho de reavaliação: revisar quando (a) mudarem os limites de 10.000 e 25.000 tokens ou o teto de 500.000 caracteres, (b) o tool search deixar de ser padrão ou mudar o limiar de 10%, (c) a ordem de precedência entre escopos mudar, ou (d) o truncamento de 2 KB em descrições de ferramenta for alterado.