Claude Code ignora o MCP instalado? Como direcionar o agente para a ferramenta certa

Você instala o servidor MCP, pede a tarefa e o Claude Code abre o Bash, lê meio projeto na unha e entrega o resultado como se a integração nunca tivesse existido

Chato demais, né? 😅

Só que na maioria das vezes isso não é teimosia do modelo

É uma dessas quatro coisas: o servidor não conectou, a ferramenta não tem permissão, a descoberta de ferramenta não trouxe a capacidade certa pro contexto, ou o pedido foi tão genérico que o agente escolheu a rota que ele já domina

E aí acontece o clássico: a pessoa reescreve o prompt de todo jeito tentando convencer o agente, quando o problema estava no status da conexão o tempo todo

Bora separar o diagnóstico da correção, sintoma por sintoma, e depois montar a escada de explicitação pra tirar a escolha da mão do agente

Sintoma 1: o agente nunca menciona a ferramenta e faz tudo por Bash

Esse é o mais fácil de diagnosticar e o mais ignorado

Se o Claude nunca cita a ferramenta, nem tenta, nem reclama, a causa mais provável é a mais boba: o servidor simplesmente não conectou

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 116 aulas
• 4 projetos
• 9h 23min

Conhecer formação

Como checar o status:

Dentro da sessão, o comando /mcp sem argumento imprime um resumo em texto do status dos servidores

Fora da sessão interativa, os comandos de CLI mostram o detalhe da falha:

# lista os servidores; quando um está com '✘ Failed to connect',
# o detalhe da falha vem anexado na linha de status
claude mcp list

# detalhe de um servidor específico
claude mcp get github

O claude mcp get <nome> mostra o detalhe numa linha Issue:, com o status HTTP ou código de erro e o texto de erro devolvido pelo servidor

Ou seja: você para de adivinhar e lê o que o servidor respondeu

Cuidado com a falha passageira:

Nem toda falha é permanente

As requisições de descoberta de capacidade que rodam depois de uma conexão bem sucedida (tools/list, prompts/list, resources/list) tentam de novo em erros transitórios de rede e de servidor, até três vezes, com backoff curto

Então vale reabrir a sessão e olhar o status de novo antes de sair mexendo em configuração

Como prevenir: checa o status ANTES de culpar o prompt

É literalmente um comando

Sintoma 2: o Claude sabe que a ferramenta existe, mas resolve por fora

Esse é o sintoma que mais parece teimosia

O agente conhece a integração, comenta que ela está ali, e mesmo assim vai de Bash

Causa provável: permissão

Ferramentas MCP exigem permissão explícita antes de o Claude poder usá-las

Sem permissão, ele vê que as ferramentas existem mas não consegue chamá-las

Sacou? É EXATAMENTE o retrato de ‘viu o MCP e foi na mão’

O caso do .mcp.json na raiz do projeto:

Tem um detalhe que pega muita gente em projeto compartilhado

O Claude SEMPRE pede aprovação antes de usar um servidor vindo do .mcp.json

Se a pessoa perde o prompt de aprovação (aquele next, next sem ler) ou nega sem querer, o Claude não usa aquele servidor

E o time inteiro fica achando que ‘o MCP tá quebrado no repo’

As configurações que resolvem isso:

Dá pra liberar ou bloquear os servidores vindos de arquivos .mcp.json via configuração:

{
  "enabledMcpjsonServers": ["github"],
  "disabledMcpjsonServers": ["servidor-que-nao-deve-rodar"]
}

O enabledMcpjsonServers habilita servidores de arquivos .mcp.json quando comitado no .claude/settings.json do projeto

Detalhe importante: em pastas não confiáveis, ainda exige aceitar o diálogo de confiança da pasta

Já o disabledMcpjsonServers bloqueia os servidores listados em todos os modos de permissão

Tome cuidado com o disallowedTools:

Aqui mora uma pegadinha ótima de entender

O disallowedTools das regras de permissão adiciona entradas à lista de negação e controla se a chamada de ferramenta é aprovada, não se a ferramenta está disponível para o Claude

Traduzindo: uma entrada esquecida ali derruba a chamada sem sumir com a ferramenta

O agente continua vendo a ferramenta, tenta, apanha, e cai no plano B manual

Sintoma 3: a ferramenta só aparece às vezes, dependendo da tarefa

Esse é o sintoma mais confuso, porque em um pedido funciona e no outro não

A causa aqui costuma ser o tool search

Que tool search? É o mecanismo que evita carregar todas as definições de ferramenta no contexto de uma vez

Ele é ligado por padrão (com exceções) e, quando ativo, as definições de ferramenta ficam fora da janela de contexto: o agente recebe um resumo das ferramentas disponíveis e busca as relevantes quando a tarefa exige uma capacidade ainda não carregada

A consequência prática é direta: pedido vago não dispara a busca pela capacidade certa

Se você escreve ‘dá uma olhada nas pendências do projeto’, o agente não tem motivo forte pra ir atrás de uma capacidade específica

Agora, se você nomeia a capacidade (listar issues, consultar o banco, buscar o documento), a busca tem o que procurar

É o mesmo raciocínio de context engineering no Claude Code: o que não está claro no contexto não existe pro agente

Se você quiser todas as definições carregadas:

A variável de ambiente ENABLE_TOOL_SEARCH sobrescreve o comportamento padrão do tool search, e ENABLE_TOOL_SEARCH=false desliga

Porém tem um porém: com CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS definido, o tool search fica desligado e não dá pra sobrescrever via ENABLE_TOOL_SEARCH

Nota rápida pra quem usa o Agent SDK:

Lá o jogo é um pouco diferente, se liga

No Agent SDK, ENABLE_TOOL_SEARCH é configurado na opção env da chamada query()

O valor auto:5 faz o tool search ativar quando as ferramentas passam de 5% do contexto, e false desliga, carregando todas as definições de ferramenta a cada turno

No modo auto, o SDK soma cada definição que o tool search pode adiar (ferramentas MCP não marcadas como alwaysLoad, de qualquer servidor, mais as ferramentas embutidas de carregamento sob demanda) num limiar combinado

Embutidas essenciais como Bash, Read e Edit são sempre carregadas e não contam para o limiar

Sintoma 4: o MCP é redundante com algo que o agente já sabe fazer

Esse é o mais humano de todos, haha

Você pede o objetivo e não o caminho

Aí o agente faz o que qualquer profissional faria: escolhe a rota que ele já domina de olhos fechados (ler arquivo, rodar comando) em vez da integração que ele mal conhece

Se a tarefa é ‘me diz o que está aberto no repositório’, ler os arquivos e rodar comando resolve

A integração vira opcional, e opcional o agente descarta

A correção não é implorar, é citar o alvo

O nome da ferramenta é previsível:

Esse é o pulo do gato

Ferramentas de MCP no Claude Code seguem um padrão de nome previsível, e é esse nome que você usa pra citar a ferramenta em regras e configurações

E esse nome completo não serve só pro prompt

Ele é o nome usado em regras de permissão, no allowed-tools de uma skill, no campo tools de um subagente e em matcher de hook

Ou seja: aprender esse padrão resolve vários problemas diferentes de uma vez 😀

Como prevenir: descreva a tarefa pela capacidade específica, não pelo resultado genérico

É a mesma lógica de resolver sem instalar biblioteca nova: quando você não fecha o caminho, o agente escolhe o dele

Sintoma 5: a ferramenta roda, mas o resultado some e o agente volta pro manual

Esse aqui é sorrateiro

A ferramenta é chamada, você vê a chamada acontecer, e do nada o agente abandona e volta pro Bash

Causa: limite de tokens de saída

O Claude Code mostra aviso quando a saída de ferramenta MCP passa de 10.000 tokens e limita a saída a 25.000 tokens por padrão

E quando passa do limite, o resultado não some de vez

Resultado maior que 25.000 tokens é salvo em arquivo, e o resultado da ferramenta é substituído por uma mensagem de erro que nomeia o caminho do arquivo, pra o agente ler a saída em partes

Só que se o pedido não deixar claro que é pra continuar dali, o agente lê aquilo como falha e improvisa

O que fazer:

• pedir uma consulta mais estreita (filtro, recorte, período), em vez de puxar tudo
• mandar o agente ler o arquivo indicado na mensagem, em partes
• elevar o limite com a variável de ambiente MAX_MCP_OUTPUT_TOKENS
• do lado do servidor, declarar limite maior por ferramenta com a anotação anthropic/maxResultSizeChars

Como prevenir: filtra o escopo no pedido ANTES de chamar

Puxar o mundo inteiro e depois reclamar do corte é receita de retrabalho

Como direcionar o Claude Code para a ferramenta MCP certa

Bora pra parte prática?

A ideia é uma escada de explicitação: começa no mais leve (o pedido) e só sobe pro mais forte (bloqueio de verdade) quando o leve não resolveu

1. Cite o nome exato da ferramenta no pedido, no formato mcp__servidor__ferramenta

Use a ferramenta mcp__github__list_issues para levantar as issues abertas
e me devolva um resumo por label

O erro comum deste passo: escrever o nome do servidor de um jeito quando o real tem caractere convertido para _

Confere o nome real antes de citar, senão você está apontando pra uma ferramenta que não existe

2. Puxe o dado direto em vez de torcer pela escolha do agente

O Claude Code busca dados de servidores MCP conectados usando o formato @servidor:recurso

É mais direto que descrever a tarefa e esperar que ele adivinhe a rota

O erro comum deste passo: usar isso esperando que substitua permissão

Não substitui

Se a ferramenta não tem permissão, o problema continua sendo o do sintoma 2

3. Use os prompts que o próprio servidor expõe

Servidores MCP podem expor prompts que aparecem como comandos na sessão, ao lado dos comandos embutidos, das skills e dos comandos customizados

O erro comum deste passo: não saber que eles existem e reescrever no prompt uma coisa que já vinha pronta do servidor

4. Deixe a regra escrita, sabendo o limite dela

Colocar no CLAUDE.md a regra de qual ferramenta usar em qual tarefa ajuda, mas entenda o que isso é: o Claude trata instruções do CLAUDE.md como contexto, não como configuração forçada

O erro comum deste passo: achar que a linha no CLAUDE.md OBRIGA o uso

Ela influencia, não obriga

5. Quando precisar de bloqueio real, vai de hook

Pra bloquear uma ação independentemente do que o Claude decidir, o caminho é um hook PreToolUse

Esse é o degrau em que a decisão sai da mão do modelo e vira mecanismo

O erro comum deste passo: pular direto pra cá antes de checar status e permissão, e aí você ganha um hook novo e o problema velho

Quando restringir o conjunto de ferramentas em vez de insistir no prompt

Tem hora que insistir no pedido é enxugar gelo

Se a tarefa se repete, a correção certa não é o prompt: é o escopo de ferramentas disponível naquele contexto

Três cenários bem comuns:

Tarefa repetitiva que você delega:

O frontmatter de subagente tem os campos tools e disallowedTools

---
tools: mcp__github__list_issues, Read
disallowedTools: Bash
---

Sem nenhum dos dois, o subagente herda todas as ferramentas disponíveis para subagentes

Com os dois definidos, disallowedTools tem precedência: a ferramenta listada nos dois é removida

Repara que aqui é o campo de frontmatter do subagente, que monta o conjunto de ferramentas dele, e não a regra de permissão do sintoma 2, que só decide se a chamada é aprovada

E o conjunto final nunca passa do que está disponível para subagentes

Fluxo específico e recorrente:

Skill resolve bem aqui

O campo de frontmatter allowed-tools limita quais ferramentas o Claude pode usar quando a skill está ativa (o exemplo da doc é allowed-tools: Read, Grep, Glob)

Na prática, isso fecha as saídas manuais enquanto a skill estiver ativa

Se a rota alternativa não está na mesa, não tem o que escolher

Time compartilhando o mesmo repo:

Aqui o inimigo é o diálogo de aprovação perdido

enabledMcpjsonServers comitado no .claude/settings.json evita que cada pessoa dependa de aceitar o prompt do .mcp.json na mão

E disabledMcpjsonServers tira da mesa o servidor que não deve rodar, em todos os modos de permissão

Um arquivo comitado vale mais que qualquer aviso no Slack, né? 😛

Conclusão

Quando o Claude Code ignora MCP, investiga sempre nesta ordem: status da conexão, permissão da ferramenta, descoberta (tool search), clareza do pedido e limite de saída

Nessa ordem mesmo, porque cada etapa custa mais tempo que a anterior e a primeira é a que mais resolve

O próximo passo prático é simples

Na próxima sessão em que o agente ignorar a integração, roda /mcp antes de qualquer coisa

Se estiver conectado e permitido, refaz o pedido citando o nome mcp__servidor__ferramenta antes de mudar UMA linha de configuração

Na maioria das vezes o problema morre aí, e você economiza uma tarde inteira de caça ao fantasma…

até o próximo post! 😀