O que você pode fazer com MCP
Com servidores MCP conectados, você pode pedir ao Claude Code para:- Implementar recursos de rastreadores de problemas: “Adicione o recurso descrito no problema JIRA ENG-4521 e crie um PR no GitHub.”
- Analisar dados de monitoramento: “Verifique Sentry e Statsig para verificar o uso do recurso descrito em ENG-4521.”
- Consultar bancos de dados: “Encontre emails de 10 usuários aleatórios que usaram o recurso ENG-4521, com base no nosso banco de dados PostgreSQL.”
- Integrar designs: “Atualize nosso modelo de email padrão com base nos novos designs do Figma que foram postados no Slack”
- Automatizar fluxos de trabalho: “Crie rascunhos do Gmail convidando esses 10 usuários para uma sessão de feedback sobre o novo recurso.”
- Reagir a eventos externos: Um servidor MCP também pode atuar como um canal que envia mensagens para sua sessão, para que Claude reaja a mensagens do Telegram, chats do Discord ou eventos de webhook enquanto você está ausente.
Encontre e crie servidores MCP
Navegue por conectores revisados no Diretório Anthropic. Os conectores do Diretório usam a mesma infraestrutura MCP que Claude Code, então você pode adicionar qualquer servidor remoto listado lá comclaude mcp add.
Para criar seu próprio servidor, consulte o guia do servidor MCP para os fundamentos do protocolo e a documentação de construção de conectores Claude para autenticação, testes e envio ao Diretório.
Você também pode fazer com que Claude crie um servidor para você com o plugin oficial mcp-server-dev.
Instale o plugin
Em uma sessão Claude Code, execute:Se Claude Code relatar que o marketplace não foi encontrado, execute
/plugin marketplace add anthropics/claude-plugins-official primeiro e depois tente novamente a instalação. Após a instalação, execute /reload-plugins para ativá-lo na sessão atual.Instalando servidores MCP
Os servidores MCP podem ser configurados de várias maneiras dependendo de suas necessidades:Opção 1: Adicionar um servidor HTTP remoto
Servidores HTTP são a opção recomendada para conectar a servidores MCP remotos. Este é o transporte mais amplamente suportado para serviços baseados em nuvem..mcp.json, ~/.claude.json, ou claude mcp add-json, o campo type aceita streamable-http como um alias para http. A especificação MCP usa o nome streamable-http para este transporte, portanto as configurações copiadas da documentação do servidor funcionam sem modificação.
Opção 2: Adicionar um servidor SSE remoto
Opção 3: Adicionar um servidor stdio local
Servidores Stdio são executados como processos locais em sua máquina. Eles são ideais para ferramentas que precisam de acesso direto ao sistema ou scripts personalizados. Claude Code defineCLAUDE_PROJECT_DIR no ambiente do servidor gerado para a raiz do projeto, para que seu servidor possa resolver caminhos relativos ao projeto sem depender do diretório de trabalho. Este é o mesmo diretório que hooks recebem em sua variável CLAUDE_PROJECT_DIR. Leia-o de dentro do seu processo de servidor, por exemplo process.env.CLAUDE_PROJECT_DIR em Node ou os.environ["CLAUDE_PROJECT_DIR"] em Python. Seu servidor também pode chamar a solicitação MCP roots/list, que retorna o diretório do qual Claude Code foi iniciado.
Esta variável é definida no ambiente do servidor, não no ambiente do próprio Claude Code, portanto referenciá-la via expansão ${VAR} em um .mcp.json com escopo de projeto ou usuário command ou args requer um padrão como ${CLAUDE_PROJECT_DIR:-.}. As configurações MCP fornecidas por plugins substituem ${CLAUDE_PROJECT_DIR} diretamente e não precisam do padrão.
Importante: Ordenação de opçõesTodas as opções (
--transport, --env, --scope, --header) devem vir antes do nome do servidor. O -- (travessão duplo) então separa o nome do servidor do comando e argumentos que são passados para o servidor MCP.Por exemplo:claude mcp add --transport stdio myserver -- npx server→ executanpx serverclaude mcp add --transport stdio --env KEY=value myserver -- python server.py --port 8080→ executapython server.py --port 8080comKEY=valueno ambiente
Opção 4: Adicionar um servidor WebSocket remoto
Servidores WebSocket mantêm uma conexão bidirecional persistente, o que é adequado para servidores MCP remotos que enviam eventos para Claude sem solicitação. Use HTTP em vez disso quando seu servidor apenas responde a solicitações, já que HTTP suporta OAuth e a flagclaude mcp add --transport, enquanto WebSocket não suporta nenhum dos dois.
Configure servidores WebSocket em .mcp.json ou com claude mcp add-json:
type: "ws" aceita os mesmos campos url, headers, headersHelper, timeout e alwaysLoad que http. A autenticação é apenas por cabeçalho, portanto passe um token estático em headers ou gere um no momento da conexão com headersHelper. A flag claude mcp add --transport não aceita ws.
Gerenciando seus servidores
Uma vez configurados, você pode gerenciar seus servidores MCP com estes comandos:.mcp.json que estão aguardando sua aprovação aparecem em claude mcp list como ⏸ Pending approval. Execute claude interativamente para revisar e aprovar. claude mcp get <name> mostra servidores pendentes como ⏸ Pending approval e servidores rejeitados como ✗ Rejected.
O painel /mcp mostra a contagem de ferramentas ao lado de cada servidor conectado e sinaliza servidores que anunciam a capacidade de ferramentas, mas não expõem nenhuma ferramenta.
Se sua solicitação precisar de ferramentas de um servidor que ainda está se conectando em segundo plano, Claude aguarda esse servidor antes de continuar. Com pesquisa de ferramentas habilitada, que é o padrão, a espera acontece dentro da chamada ToolSearch. Em configurações sem pesquisa de ferramentas, como Vertex AI, um ANTHROPIC_BASE_URL personalizado, ou ENABLE_TOOL_SEARCH=false, Claude usa a ferramenta WaitForMcpServers em vez disso.
O nome do servidor workspace é reservado para uso interno. Se sua configuração define um servidor com esse nome, Claude Code o ignora no tempo de carregamento e mostra um aviso pedindo que você o renomeie.
Atualizações dinâmicas de ferramentas
Claude Code suporta notificações MCPlist_changed, permitindo que servidores MCP atualizem dinamicamente suas ferramentas, prompts e recursos disponíveis sem exigir que você se desconecte e reconecte. Quando um servidor MCP envia uma notificação list_changed, Claude Code atualiza automaticamente as capacidades disponíveis desse servidor.
Reconexão automática
Se um servidor HTTP ou SSE se desconectar durante a sessão, Claude Code se reconecta automaticamente com backoff exponencial: até cinco tentativas, começando com um atraso de um segundo e dobrando a cada vez. O servidor aparece como pendente em/mcp enquanto a reconexão está em andamento. Após cinco tentativas falhadas, o servidor é marcado como falho e você pode tentar novamente manualmente de /mcp. Servidores Stdio são processos locais e não são reconectados automaticamente.
O mesmo backoff se aplica quando um servidor HTTP ou SSE falha sua conexão inicial na inicialização. A partir da v2.1.121, Claude Code tenta novamente a conexão inicial até três vezes em erros transitórios, como uma resposta 5xx, uma conexão recusada ou um tempo limite, e então marca o servidor como falho se ainda não conseguir se conectar. Erros de autenticação e não encontrado não são retentados porque exigem uma mudança de configuração para serem resolvidos.
Enviar mensagens com canais
Um servidor MCP também pode enviar mensagens diretamente para sua sessão para que Claude possa reagir a eventos externos como resultados de CI, alertas de monitoramento ou mensagens de chat. Para habilitar isso, seu servidor declara a capacidadeclaude/channel e você a ativa com a flag --channels na inicialização. Veja Canais para usar um canal oficialmente suportado, ou Referência de canais para construir o seu próprio.
O timeout por servidor é um limite de tempo de parede rígido por chamada de ferramenta, e notificações de progresso do servidor não o estendem. Valores abaixo de 1000 são arredondados para um segundo. Para servidores HTTP e SSE, o orçamento de primeiro byte por solicitação de busca tem um mínimo de 60 segundos independentemente deste valor, portanto apenas o watchdog de chamada de ferramenta honra valores menores.
Servidores MCP fornecidos por plugins
Plugins podem agrupar servidores MCP, fornecendo automaticamente ferramentas e integrações quando o plugin está habilitado. Os servidores MCP de plugins funcionam de forma idêntica aos servidores configurados pelo usuário. Como funcionam os servidores MCP de plugins:- Plugins definem servidores MCP em
.mcp.jsonna raiz do plugin ou inline emplugin.json - Quando um plugin está habilitado, seus servidores MCP iniciam automaticamente
- As ferramentas MCP do plugin aparecem junto com as ferramentas MCP configuradas manualmente
- Os servidores de plugins são gerenciados através da instalação de plugins (não comandos
/mcp)
.mcp.json na raiz do plugin:
plugin.json:
- Ciclo de vida automático: Na inicialização da sessão, os servidores para plugins habilitados se conectam automaticamente. Se você habilitar ou desabilitar um plugin durante uma sessão, execute
/reload-pluginspara conectar ou desconectar seus servidores MCP - Variáveis de ambiente: Use
${CLAUDE_PLUGIN_ROOT}para arquivos agrupados do plugin,${CLAUDE_PLUGIN_DATA}para estado persistente que sobrevive a atualizações de plugins, e${CLAUDE_PROJECT_DIR}para a raiz do projeto estável - Acesso a variáveis de ambiente do usuário: Acesso às mesmas variáveis de ambiente que servidores configurados manualmente
- Múltiplos tipos de transporte: Suporte para transportes stdio, SSE, HTTP e WebSocket (o suporte de transporte pode variar por servidor)
- Distribuição agrupada: Ferramentas e servidores empacotados juntos
- Configuração automática: Nenhuma configuração MCP manual necessária
- Consistência da equipe: Todos obtêm as mesmas ferramentas quando o plugin está instalado
Escopos de instalação de MCP
Os servidores MCP podem ser configurados em três escopos. O escopo que você escolhe controla em quais projetos o servidor é carregado e se a configuração é compartilhada com sua equipe. Os administradores também podem implantar servidores no nível empresarial via configuração gerenciada.Escopo local
O escopo local é o padrão. Um servidor com escopo local carrega apenas no projeto onde você o adicionou e permanece privado para você. Claude Code o armazena em~/.claude.json sob o caminho desse projeto, então o mesmo servidor não aparecerá em seus outros projetos. Use o escopo local para servidores de desenvolvimento pessoal, configurações experimentais ou servidores com credenciais que você não deseja no controle de versão.
O termo “escopo local” para servidores MCP difere das configurações locais gerais. Os servidores MCP com escopo local são armazenados em
~/.claude.json (seu diretório inicial), enquanto as configurações locais gerais usam .claude/settings.local.json (no diretório do projeto). Veja Configurações para detalhes sobre localizações de arquivos de configuração.~/.claude.json. O exemplo abaixo mostra o resultado quando você o executa de /path/to/your/project:
Escopo de projeto
Servidores com escopo de projeto permitem colaboração em equipe armazenando configurações em um arquivo.mcp.json no diretório raiz do seu projeto. Este arquivo é projetado para ser verificado no controle de versão, garantindo que todos os membros da equipe tenham acesso às mesmas ferramentas e serviços MCP. Quando você adiciona um servidor com escopo de projeto, Claude Code cria ou atualiza automaticamente este arquivo com a estrutura de configuração apropriada.
.mcp.json resultante segue um formato padronizado:
.mcp.json. Se você precisar redefinir essas escolhas de aprovação, use o comando claude mcp reset-project-choices.
Escopo de usuário
Servidores com escopo de usuário são armazenados em~/.claude.json e fornecem acessibilidade entre projetos, tornando-os disponíveis em todos os projetos em sua máquina enquanto permanecem privados para sua conta de usuário. Este escopo funciona bem para servidores de utilitários pessoais, ferramentas de desenvolvimento ou serviços que você usa frequentemente em diferentes projetos.
Hierarquia de escopo e precedência
Quando o mesmo servidor é definido em mais de um lugar, Claude Code se conecta a ele uma vez, usando a definição da fonte com maior precedência. A entrada inteira do servidor dessa fonte é usada; os campos não são mesclados entre escopos.- Escopo local
- Escopo de projeto
- Escopo de usuário
- Servidores fornecidos por plugins
- Conectores claude.ai
Expansão de variáveis de ambiente em .mcp.json
Claude Code suporta expansão de variáveis de ambiente em arquivos .mcp.json, permitindo que equipes compartilhem configurações mantendo flexibilidade para caminhos específicos da máquina e valores sensíveis como chaves de API.
Sintaxe suportada:
${VAR}- Expande para o valor da variável de ambienteVAR${VAR:-default}- Expande paraVARse definida, caso contrário usadefault
command- O caminho do executável do servidorargs- Argumentos de linha de comandoenv- Variáveis de ambiente passadas para o servidorurl- Para tipos de servidor HTTPheaders- Para autenticação de servidor HTTP
Exemplos práticos
Exemplo: Monitorar erros com Sentry
Exemplo: Conectar ao GitHub para revisões de código
O servidor MCP remoto do GitHub autentica com um token de acesso pessoal do GitHub passado como cabeçalho. Para obter um, abra suas configurações de token do GitHub, gere um novo token refinado com acesso aos repositórios com os quais você deseja que Claude trabalhe, então adicione o servidor:Exemplo: Consultar seu banco de dados PostgreSQL
Autenticar com servidores MCP remotos
Muitos servidores MCP baseados em nuvem exigem autenticação. Claude Code suporta OAuth 2.0 para conexões seguras. Claude Code marca um servidor remoto como necessitando autenticação quando o servidor responde com401 Unauthorized ou 403 Forbidden. Qualquer código de status sinaliza o servidor em /mcp para que você possa completar o fluxo OAuth. Um servidor personalizado que retorna um cabeçalho WWW-Authenticate apontando para seu servidor de autorização obtém a mesma descoberta automática que qualquer outro servidor remoto.
Se você configurou headers.Authorization para o servidor e o servidor rejeita esse cabeçalho, Claude Code relata a conexão como falha em vez de voltar para OAuth. Verifique se o token é válido para o endpoint MCP, ou remova o cabeçalho para usar o fluxo OAuth.
Usar uma porta de callback OAuth fixa
Alguns servidores MCP exigem um URI de redirecionamento específico registrado antecipadamente. Por padrão, Claude Code escolhe uma porta aleatória disponível para o callback OAuth. Use--callback-port para fixar a porta para que corresponda a um URI de redirecionamento pré-registrado do formulário http://localhost:PORT/callback.
Você pode usar --callback-port sozinho (com registro dinâmico de cliente) ou junto com --client-id (com credenciais pré-configuradas).
Usar credenciais OAuth pré-configuradas
Alguns servidores MCP não suportam configuração automática de OAuth via Registro Dinâmico de Cliente. Se você vir um erro como “Incompatible auth server: does not support dynamic client registration,” o servidor requer credenciais pré-configuradas. Claude Code também suporta servidores que usam um Documento de Metadados de ID do Cliente (CIMD) em vez de Registro Dinâmico de Cliente, e descobre esses automaticamente. Se a descoberta automática falhar, registre um aplicativo OAuth através do portal do desenvolvedor do servidor primeiro, depois forneça as credenciais ao adicionar o servidor.Registre um aplicativo OAuth com o servidor
Crie um aplicativo através do portal do desenvolvedor do servidor e anote seu ID do cliente e segredo do cliente.Muitos servidores também exigem um URI de redirecionamento. Se assim for, escolha uma porta e registre um URI de redirecionamento no formato
http://localhost:PORT/callback. Use essa mesma porta com --callback-port na próxima etapa.Adicione o servidor com suas credenciais
Escolha um dos seguintes métodos. A porta usada para
--callback-port pode ser qualquer porta disponível. Ela apenas precisa corresponder ao URI de redirecionamento que você registrou na etapa anterior.- claude mcp add
- claude mcp add-json
- claude mcp add-json (apenas porta de callback)
- CI / variável de ambiente
Use
--client-id para passar o ID do cliente do seu aplicativo. A flag --client-secret solicita o segredo com entrada mascarada:Substituir descoberta de metadados OAuth
Aponte Claude Code para uma URL de metadados específica de servidor de autorização OAuth para contornar a cadeia de descoberta padrão. DefinaauthServerMetadataUrl quando os endpoints padrão do servidor MCP falharem, ou quando você deseja rotear a descoberta através de um proxy interno. Por padrão, Claude Code primeiro verifica os Metadados de Recurso Protegido RFC 9728 em /.well-known/oauth-protected-resource, depois volta para os metadados do servidor de autorização RFC 8414 em /.well-known/oauth-authorization-server.
Defina authServerMetadataUrl no objeto oauth da configuração do seu servidor em .mcp.json:
https://. authServerMetadataUrl requer Claude Code v2.1.64 ou posterior. Os scopes_supported da URL de metadados substituem os escopos que o servidor upstream anuncia.
Restringir escopos OAuth
Definaoauth.scopes para fixar os escopos que Claude Code solicita durante o fluxo de autorização. Esta é a forma suportada de restringir um servidor MCP a um subconjunto aprovado pela equipe de segurança quando o servidor de autorização upstream anuncia mais escopos do que você deseja conceder. O valor é uma única string separada por espaço, correspondendo ao formato do parâmetro scope em RFC 6749 §3.3.
oauth.scopes tem precedência sobre authServerMetadataUrl e os escopos que o servidor descobre em /.well-known. Deixe-o indefinido para permitir que o servidor MCP determine o conjunto de escopos solicitado.
Se o servidor de autorização anuncia offline_access em scopes_supported, Claude Code o acrescenta aos escopos fixados para que o token de acesso possa ser atualizado sem um novo login no navegador.
Se o servidor depois retorna um 403 insufficient_scope para uma chamada de ferramenta, Claude Code se autentica novamente com os mesmos escopos fixados. Amplie oauth.scopes quando uma ferramenta que você precisa requer um escopo fora do pino.
Usar cabeçalhos dinâmicos para autenticação personalizada
Se seu servidor MCP usar um esquema de autenticação diferente de OAuth (como Kerberos, tokens de curta duração ou um SSO interno), useheadersHelper para gerar cabeçalhos de solicitação no momento da conexão. Claude Code executa o comando e mescla sua saída nos cabeçalhos de conexão.
- O comando deve escrever um objeto JSON de pares chave-valor de string para stdout
- O comando é executado em um shell com um tempo limite de 10 segundos
- Cabeçalhos dinâmicos substituem qualquer
headersestático com o mesmo nome
| Variável | Valor |
|---|---|
CLAUDE_CODE_MCP_SERVER_NAME | o nome do servidor MCP |
CLAUDE_CODE_MCP_SERVER_URL | a URL do servidor MCP |
headersHelper executa comandos shell arbitrários. Quando definido no escopo de projeto ou local, ele só é executado após você aceitar o diálogo de confiança do espaço de trabalho.Adicionar servidores MCP de configuração JSON
Se você tiver uma configuração JSON para um servidor MCP, você pode adicioná-la diretamente:Importar servidores MCP do Claude Desktop
Se você já configurou servidores MCP no Claude Desktop, você pode importá-los:Selecione quais servidores importar
Após executar o comando, você verá um diálogo interativo que permite selecionar quais servidores você deseja importar.
Usar servidores MCP do Claude.ai
Se você fez login no Claude Code com uma conta Claude.ai, os servidores MCP que você adicionou no Claude.ai estão automaticamente disponíveis no Claude Code:Configure servidores MCP no Claude.ai
Adicione servidores em claude.ai/customize/connectors. Em planos Team e Enterprise, apenas administradores podem adicionar servidores.
Show unused connectors no final da seção claude.ai, para que uma lista provisionada pela organização não preencha o painel. Selecione a linha para expandi-los. Um conector ao qual você fez login antes permanece visível mesmo quando atualmente precisa de re-autenticação.
Os conectores do Claude.ai são buscados apenas quando seu método de autenticação ativo é sua assinatura do Claude.ai. Eles não são carregados quando ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, apiKeyHelper, ou um provedor de terceiros como Bedrock ou Vertex está ativo, mesmo que você tenha executado /login anteriormente. Se /mcp não listar um conector que você adicionou, execute /status para confirmar qual método de autenticação está ativo, desdefina essa variável de ambiente ou remova a configuração apiKeyHelper, depois execute /login para selecionar sua conta do Claude.ai.
Um servidor que você adicionou no Claude Code tem precedência sobre um conector do claude.ai que aponta para a mesma URL. Quando isso acontece, /mcp lista o conector como oculto e mostra como remover a duplicata se você preferir usar o conector.
Para desabilitar servidores MCP do claude.ai no Claude Code, defina a variável de ambiente ENABLE_CLAUDEAI_MCP_SERVERS como false:
Usar Claude Code como um servidor MCP
Você pode usar Claude Code em si como um servidor MCP que outros aplicativos podem se conectar:Limites de saída MCP e avisos
Quando as ferramentas MCP produzem grandes saídas, Claude Code ajuda a gerenciar o uso de tokens para evitar sobrecarregar seu contexto de conversa:- Limite de aviso de saída: Claude Code exibe um aviso quando qualquer saída de ferramenta MCP excede 10.000 tokens
- Limite configurável: você pode ajustar o máximo de tokens de saída MCP permitidos usando a variável de ambiente
MAX_MCP_OUTPUT_TOKENS - Limite padrão: o máximo padrão é 25.000 tokens
- Escopo: a variável de ambiente se aplica a ferramentas que não declaram seu próprio limite. Ferramentas que definem
anthropic/maxResultSizeCharsusam esse valor em vez disso para conteúdo de texto, independentemente do queMAX_MCP_OUTPUT_TOKENSestá definido. Ferramentas que retornam dados de imagem ainda estão sujeitas aMAX_MCP_OUTPUT_TOKENS
- Consultam grandes conjuntos de dados ou bancos de dados
- Geram relatórios ou documentação detalhados
- Processam arquivos de log extensos ou informações de depuração
Aumentar o limite para uma ferramenta específica
Se você está construindo um servidor MCP, você pode permitir que ferramentas individuais retornem resultados maiores do que o limite padrão de persistência em disco definindo_meta["anthropic/maxResultSizeChars"] na entrada da ferramenta em resposta tools/list. Claude Code aumenta o limite dessa ferramenta para o valor anotado, até um teto rígido de 500.000 caracteres.
Isso é útil para ferramentas que retornam saídas inerentemente grandes mas necessárias, como esquemas de banco de dados ou árvores de arquivos completas. Sem a anotação, resultados que excedem o limite padrão são persistidos em disco e substituídos por uma referência de arquivo na conversa.
MAX_MCP_OUTPUT_TOKENS para conteúdo de texto, então os usuários não precisam aumentar a variável de ambiente para ferramentas que a declaram. Ferramentas que retornam dados de imagem ainda estão sujeitas ao limite de token.
Responder a solicitações de elicitação MCP
Os servidores MCP podem solicitar entrada estruturada de você durante uma tarefa usando elicitação. Quando um servidor precisa de informações que não consegue obter por conta própria, Claude Code exibe um diálogo interativo e passa sua resposta de volta para o servidor. Nenhuma configuração é necessária do seu lado: diálogos de elicitação aparecem automaticamente quando um servidor os solicita. Os servidores podem solicitar entrada de duas maneiras:- Modo de formulário: Claude Code mostra um diálogo com campos de formulário definidos pelo servidor (por exemplo, um prompt de nome de usuário e senha). Preencha os campos e envie.
- Modo de URL: Claude Code abre uma URL do navegador para autenticação ou aprovação. Complete o fluxo no navegador, depois confirme no CLI.
Elicitation.
Se você está construindo um servidor MCP que usa elicitação, veja a especificação de elicitação MCP para detalhes de protocolo e exemplos de esquema.
Usar recursos MCP
Os servidores MCP podem expor recursos que você pode referenciar usando menções @, semelhante a como você referencia arquivos.Referenciar recursos MCP
Liste recursos disponíveis
Digite
@ no seu prompt para ver recursos disponíveis de todos os servidores MCP conectados. Os recursos aparecem junto com arquivos no menu de preenchimento automático.Referencie um recurso específico
Use o formato
@server:protocol://resource/path para referenciar um recurso:Escalar com MCP Tool Search
Tool Search mantém o uso de contexto MCP baixo adiando definições de ferramentas até que Claude precise delas. Apenas nomes de ferramentas e instruções do servidor são carregados no início da sessão, então adicionar mais servidores MCP tem impacto mínimo na sua janela de contexto.Como funciona
Tool Search é ativado por padrão. As ferramentas MCP são adiadas em vez de carregadas no contexto antecipadamente, e Claude usa uma ferramenta de pesquisa para descobrir as relevantes quando uma tarefa precisa delas. Apenas as ferramentas que Claude realmente usa entram no contexto. Da sua perspectiva, as ferramentas MCP funcionam exatamente como antes. Se você preferir carregamento baseado em limite, definaENABLE_TOOL_SEARCH=auto para carregar esquemas antecipadamente quando se encaixarem em 10% da janela de contexto e adiar apenas o excesso. Veja Configurar pesquisa de ferramentas para todas as opções.
Para autores de servidores MCP
Se você está construindo um servidor MCP, o campo de instruções do servidor se torna mais útil com Tool Search habilitado. As instruções do servidor ajudam Claude a entender quando pesquisar suas ferramentas, semelhante a como skills funcionam. Adicione instruções de servidor claras e descritivas que expliquem:- Que categoria de tarefas suas ferramentas lidam
- Quando Claude deve pesquisar suas ferramentas
- Capacidades principais do seu servidor
Configurar pesquisa de ferramentas
Tool Search é ativado por padrão: as ferramentas MCP são adiadas e descobertas sob demanda. Claude Code desabilita-o por padrão no Vertex AI. Também é desabilitado quandoANTHROPIC_BASE_URL aponta para um host que não é de primeira parte, já que a maioria dos proxies não encaminha blocos tool_reference. Defina ENABLE_TOOL_SEARCH explicitamente para substituir qualquer fallback.
Tool Search requer um modelo que suporte blocos tool_reference: Sonnet 4 e posterior, ou Opus 4 e posterior. Os modelos Haiku não suportam. No Vertex AI, tool search é suportado para Claude Sonnet 4.5 e posterior e Claude Opus 4.5 e posterior.
Controle o comportamento da pesquisa de ferramentas com a variável de ambiente ENABLE_TOOL_SEARCH:
| Valor | Comportamento |
|---|---|
| (não definido) | Todas as ferramentas MCP adiadas e carregadas sob demanda. Volta a carregar antecipadamente no Vertex AI ou quando ANTHROPIC_BASE_URL é um host que não é de primeira parte |
true | Todas as ferramentas MCP adiadas. Claude Code envia o cabeçalho beta mesmo no Vertex AI e através de proxies. As solicitações falham em modelos Vertex AI anteriores a Sonnet 4.5 ou Opus 4.5, ou em proxies que não suportam blocos tool_reference |
auto | Modo de limite: ferramentas carregam antecipadamente se se encaixarem em 10% da janela de contexto, adiadas caso contrário |
auto:N | Modo de limite com uma porcentagem personalizada, onde N é 0-100. Por exemplo, auto:5 para 5% |
false | Todas as ferramentas MCP carregadas antecipadamente, sem adiamento |
env de settings.json.
Você também pode desabilitar a ferramenta ToolSearch especificamente:
Isentar um servidor de adiamento
Se as ferramentas de um servidor devem estar sempre visíveis para Claude sem uma etapa de pesquisa, definaalwaysLoad como true na configuração desse servidor. Cada ferramenta desse servidor então carrega no contexto no início da sessão independentemente da configuração ENABLE_TOOL_SEARCH. Use isso para um pequeno número de ferramentas que Claude precisa a cada turno, já que cada ferramenta antecipada consome contexto que estaria disponível para sua conversa.
A seguinte entrada .mcp.json isenta um servidor HTTP enquanto deixa outros servidores adiados:
alwaysLoad está disponível em todos os tipos de servidor e requer Claude Code v2.1.121 ou posterior. Um servidor MCP também pode marcar ferramentas individuais como sempre carregadas incluindo "anthropic/alwaysLoad": true no objeto _meta da ferramenta, que tem o mesmo efeito apenas para essa ferramenta.
Definir alwaysLoad: true também bloqueia a inicialização até que o servidor se conecte, limitado ao tempo limite de conexão padrão de 5 segundos. Isso se aplica mesmo que a inicialização MCP seja não bloqueante por padrão, já que as ferramentas devem estar presentes quando o primeiro prompt é construído. Outros servidores continuam a se conectar em segundo plano.
Usar prompts MCP como comandos
Os servidores MCP podem expor prompts que se tornam disponíveis como comandos no Claude Code.Executar prompts MCP
Descubra prompts disponíveis
Digite
/ para ver todos os comandos disponíveis, incluindo aqueles de servidores MCP. Os prompts MCP aparecem com o formato /mcp__servername__promptname.Configuração MCP gerenciada
Para organizações que precisam de controle centralizado sobre quais servidores MCP os usuários podem se conectar, consulte Configuração MCP gerenciada. Ela aborda a implantação de um conjunto fixo de servidores commanaged-mcp.json, restrição de servidores com allowedMcpServers e deniedMcpServers, e o que os usuários veem quando um servidor é bloqueado.