Conectar Claude Code a ferramentas via MCP

Aprenda como conectar Claude Code às suas ferramentas com o Model Context Protocol.

Claude Code pode se conectar a centenas de ferramentas e fontes de dados externas através do Model Context Protocol (MCP), um padrão de código aberto para integrações de IA com ferramentas. Os servidores MCP dão ao Claude Code acesso às suas ferramentas, bancos de dados e APIs.

Conecte um servidor quando você se encontrar copiando dados para o chat de outra ferramenta, como um rastreador de problemas ou um painel de monitoramento. Uma vez conectado, Claude pode ler e agir nesse sistema diretamente em vez de trabalhar com o que você cola.

Se você está conectando seu primeiro servidor, comece com o guia de início rápido do MCP para um passo a passo detalhado. Esta página é a referência completa.

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á com claude mcp add.

[!WARNING]

Verifique se você confia em cada servidor antes de conectá-lo. Servidores que buscam conteúdo externo podem expô-lo ao risco de injeção de prompt.

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.

1. Instale o plugin

Na extensão do VS Code ou no aplicativo desktop, siga Instalar um plugin em vez desta etapa. Em um terminal, inicie Claude Code executando claude e, em seguida, insira isto no prompt:

/plugin install mcp-server-dev@claude-plugins-official

Se a instalação falhar, corresponda à mensagem que Claude Code relata:

• Marketplace "claude-plugins-official" not found: adicione o marketplace com /plugin marketplace add anthropics/claude-plugins-official, depois tente novamente a instalação.
• Plugin "<name>" not found in marketplace "claude-plugins-official": sua cópia local do catálogo do marketplace pode estar desatualizada. Atualize-a com /plugin marketplace update claude-plugins-official e, em seguida, tente novamente a instalação. Se a nova tentativa exibir a mesma mensagem, consulte Plugin não encontrado no marketplace.

Se o resumo da instalação relatar Run /reload-plugins to apply., Claude Code então executa esse recarregamento para você. Se o recarregamento avisar que sua próxima mensagem releria a conversa, execute /reload-plugins --force.

2. Execute a skill de build

/mcp-server-dev:build-mcp-server

Claude pergunta sobre seu caso de uso e cria um servidor HTTP remoto ou servidor stdio local.

Instalando servidores MCP

Os servidores MCP podem ser configurados de várias maneiras, dependendo das suas necessidades:

Opção 1: Adicionar um servidor HTTP remoto

Os servidores HTTP são a opção recomendada para se conectar a servidores MCP remotos. Este é o transporte com maior suporte para serviços baseados em nuvem.

# Basic syntax
claude mcp add --transport http <name> <url>

# Real example: Connect to Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Example with Bearer token
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Ao configurar servidores MCP via JSON em .mcp.json, ~/.claude.json ou claude mcp add-json, o campo type aceita streamable-http como alias para http. A especificação MCP usa o nome streamable-http para este transporte, então configurações copiadas da documentação do servidor funcionam sem modificação.

Uma entrada JSON que tem um url, mas nenhum type, é um erro de configuração, porque o Claude Code lê uma entrada sem type como um servidor stdio. O Claude Code ignora esse servidor e informa MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry.

Somente um aplicativo host do SDK, como um aplicativo do Agent SDK ou o aplicativo desktop, pode registrar um servidor em processo "type": "sdk". O Claude Code ignora uma entrada "type": "sdk" em .mcp.json, ~/.claude.json ou nas configurações e informa Skipped — MCP server "<name>" declares type "sdk", which only an SDK host application can register.

[!NOTE]

Em execuções com --output-format stream-json, o Claude Code também informa uma entrada --mcp-config ignorada no campo mcp_server_errors do evento system/init, para que scripts possam detectar que o servidor nunca foi carregado.

Opção 2: Adicionar um servidor SSE remoto

[!WARNING]

O transporte SSE (Server-Sent Events) está descontinuado. Use servidores HTTP, quando disponíveis.

Alguns serviços ainda expõem apenas um endpoint SSE. Adicione-os com o mesmo comando claude mcp add --transport http <name> <url> usado para um servidor HTTP. O Claude Code tenta primeiro o transporte HTTP e muda para SSE quando o servidor não o aceita. A mudança automática requer o Claude Code v2.1.265 ou posterior.

Em uma versão anterior, ou para se conectar diretamente via SSE, passe --transport sse:

# Basic syntax
claude mcp add --transport sse <name> <url>

# Real example: Connect to Asana
claude mcp add --transport sse asana https://mcp.asana.com/sse

# Example with authentication header
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

Opção 3: Adicionar um servidor stdio local

Os servidores stdio são executados como processos locais na sua máquina. Eles são ideais para ferramentas que precisam de acesso direto ao sistema ou scripts personalizados.

O Claude Code define CLAUDE_PROJECT_DIR no ambiente do servidor iniciado como 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 os hooks recebem em sua variável CLAUDE_PROJECT_DIR. Leia-o de dentro do processo do seu servidor, por exemplo process.env.CLAUDE_PROJECT_DIR em Node ou os.environ["CLAUDE_PROJECT_DIR"] em Python.

CLAUDE_PROJECT_DIR é a raiz estável do projeto e não muda quando você adiciona ou remove diretórios de trabalho no meio da sessão. Um servidor que limita seu próprio acesso ao sistema de arquivos a um conjunto de diretórios permitidos deve implementar a requisição MCP roots/list. O Claude Code responde a roots/list com o diretório de inicialização da sessão mais cada diretório de trabalho adicional que você concedeu com --add-dir, /add-dir ou a configuração additionalDirectories. O Claude Code envia notifications/roots/list_changed quando esse conjunto muda.

Essa variável é definida no ambiente do servidor, não no ambiente do próprio Claude Code, portanto referenciá-la via expansão ${VAR} no command ou args de uma entrada .mcp.json com escopo de projeto, ou de uma entrada de servidor com escopo local ou de usuário em ~/.claude.json, requer um valor padrão como ${CLAUDE_PROJECT_DIR:-.}. As configurações MCP fornecidas por plugins substituem ${CLAUDE_PROJECT_DIR} diretamente e não precisam do valor padrão.

# Basic syntax
claude mcp add [options] <name> -- <command> [args...]

# Real example: Add Airtable server
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

[!NOTE]

Para servidores stdio, o -- (traço duplo) separa as opções do próprio Claude, como --transport, --env e --scope, do comando e dos argumentos que executam o servidor. Tudo após -- é passado ao servidor sem alterações.

Por exemplo:

• claude mcp add --transport stdio myserver -- npx server → executa npx server
• claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080 → executa python server.py --port 8080 com KEY=value no ambiente

Sem --, o Claude Code tentaria interpretar as flags do servidor, como --port acima, como suas próprias opções.

--env aceita vários pares KEY=value. Se o nome do servidor vier diretamente após --env, a CLI lê o nome como outro par e o rejeita, então coloque pelo menos uma outra opção, como --transport stdio, entre --env e o nome do servidor.

Como o Claude Code encerra um servidor stdio

Quando o Claude Code desconecta um servidor stdio, por exemplo quando sua sessão termina, ele envia um sinal ao processo do servidor e aguarda brevemente que ele saia antes de forçá-lo a parar. Se o seu servidor salva estado ou remove arquivos de bloqueio no encerramento, trate o sinal da sua plataforma e conclua dentro desse tempo:

• No macOS e Linux: o Claude Code envia SIGINT, depois SIGTERM se o processo ainda estiver em execução 100 milissegundos depois, e então SIGKILL após mais 400 milissegundos.
• No Windows: o Claude Code fecha o stdin do servidor e depois encerra a árvore de processos do servidor se o processo ainda estiver em execução 300 milissegundos depois.

Antes da v2.1.296, o Claude Code no Windows encerrava a árvore de processos do servidor imediatamente, sem fechar o stdin primeiro nem aguardar.

Opção 4: Adicionar um servidor WebSocket remoto

Os servidores WebSocket mantêm uma conexão bidirecional persistente, o que é adequado para servidores MCP remotos que enviam eventos ao Claude sem solicitação. Use HTTP quando o seu servidor apenas responde a requisições, já que o HTTP oferece suporte a OAuth e à flag claude mcp add --transport, enquanto o WebSocket não oferece suporte a nenhum dos dois.

Configure servidores WebSocket em .mcp.json ou com claude mcp add-json:

claude mcp add-json events-server \
  '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

A entrada type: "ws" aceita os mesmos campos url, headers, headersHelper, timeout e alwaysLoad que http. A autenticação é feita apenas por cabeçalho, então 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.

Adicionar um servidor a partir de instruções de configuração escritas para outro cliente

Os servidores MCP não são específicos do Claude Code, então as instruções de configuração de um servidor podem ter sido escritas para o Claude Desktop, o Cursor ou outro cliente MCP e não fornecer nenhum comando claude mcp add. Para adicionar o servidor mesmo assim, procure nessas instruções uma URL, um comando de inicialização ou um bloco JSON:

• Uma URL como https://mcp.example.com/mcp: o servidor é remoto.
• Um comando de inicialização como npx -y @example/mcp-server: o servidor é executado na sua máquina.
• Um bloco JSON mcpServers: configuração escrita para o arquivo de configuração de outro cliente.

Cada um deles é uma das entradas que as quatro opções em Instalando servidores MCP recebem. Encontre abaixo o formato que você tem para transformá-lo no comando que o Claude Code aceita. Cada comando grava no escopo local, a menos que você adicione --scope project ou --scope user.

Adicionar um servidor a partir de uma URL

Uma URL significa que o servidor é remoto. Para um endpoint https://, adicione-o com --transport http, ou siga a Opção 2 quando as instruções disserem que o endpoint usa SSE. Para um endpoint wss://, use a Opção 4, já que --transport não aceita ws:

claude mcp add --transport http example https://mcp.example.com/mcp

Se as instruções também fornecerem uma chave de API ou um cabeçalho de token, passe-o com --header, conforme mostrado na Opção 1.

Adicionar um servidor a partir de um comando npx, uvx ou binário

Um comando de inicialização significa que o servidor é executado como um processo stdio local. Coloque o comando inteiro após --, para que o Claude Code passe flags como -y ao comando que inicia o servidor em vez de lê-las como suas próprias opções. Passe quaisquer variáveis de ambiente que as instruções pedirem com --env, após o nome do servidor e antes de --:

claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server

A Opção 3 aborda o separador -- em detalhes.

Adicionar um servidor a partir de um bloco JSON mcpServers

Um bloco mcpServers escrito para outro cliente MCP, como o Claude Desktop, usa a chave envolvente e o formato de entrada que o Claude Code lê. Passe para claude mcp add-json o objeto dentro de mcpServers, não o envoltório. Duas entradas precisam de um ajuste antes:

• Um url sem type: adicione "type": "http", "type": "sse" ou "type": "ws" de acordo com o endpoint. O Claude Code lê uma entrada sem type como um servidor stdio, então uma entrada url sem type falha.
• Uma chave com caracteres diferentes de letras, números, hifens e sublinhados: escolha um nome de servidor que use apenas esses caracteres. Caso contrário, a chave é o nome do servidor.

Por exemplo, este bloco:

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"]
    }
  }
}

torna-se este comando:

claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

Adicionar servidores MCP a partir de configuração JSON aborda o escape no shell e a flag --scope para add-json. Para compartilhar o servidor com sua equipe, adicione --scope project, ou adicione a entrada em mcpServers no .mcp.json na raiz do seu projeto e faça commit dela. Escopo de projeto explica como o Claude Code carrega e aprova esse arquivo.

Cada comando claude mcp add e claude mcp add-json imprime uma linha Added ... em caso de sucesso. Para verificar se o Claude Code se conectou, execute claude mcp get <name>; Status do servidor aborda os status exibidos e a etapa de aprovação para servidores do .mcp.json.

Gerenciando seus servidores

Depois de configurados, você pode gerenciar seus servidores MCP com estes comandos:

# List all configured servers
claude mcp list

# Get details for a specific server
claude mcp get notion

# Remove a server
claude mcp remove notion

# (within Claude Code) Check server status
/mcp

Quando você remove um servidor remoto, o Claude Code também exclui os tokens OAuth e o registro de cliente que armazenou para esse servidor. O Claude Code não revoga os tokens no servidor de autorização que os emitiu. Para revogar os tokens onde o servidor de autorização oferece suporte à revogação, execute claude mcp logout <name> no seu shell antes de claude mcp remove <name>.

Status do servidor

claude mcp add confirma uma adição bem-sucedida imprimindo uma linha Added ..., o que significa que a configuração foi gravada. Se o comando imprimir uma mensagem was not saved, consulte O servidor MCP não foi salvo ou removido; para uma mensagem may not have been saved, consulte O servidor MCP pode não ter sido salvo ou removido.

claude mcp list mostra um status de integridade ao lado de cada servidor listado, como ✔ Connected, ! Needs authentication ou ✘ Failed to connect. Um status de falha significa que o Claude Code não conseguiu se conectar a esse servidor, não que o comando de listagem falhou.

Os status nesta lista informam uma decisão de configuração em vez de uma tentativa de conexão, então o Claude Code os imprime sem se conectar ao servidor:

• ⏸ Pending approval (run `claude` to approve): um servidor com escopo de projeto do .mcp.json que você ainda não aprovou. O Claude Code o mostra tanto em claude mcp list quanto em claude mcp get <name>. Execute claude interativamente para revisá-lo e aprová-lo.
• ✘ Rejected (see disabledMcpjsonServers in settings): um servidor do .mcp.json que uma entrada disabledMcpjsonServers rejeita. O Claude Code o mostra apenas em claude mcp get <name>.
• ⊘ Disabled for this project (re-enable via /mcp): um servidor que a lista disabledMcpServers do projeto nomeia. O Claude Code o mostra tanto em claude mcp list quanto em claude mcp get <name>. Reative o servidor no painel /mcp.
• ✘ Blocked by enterprise managed policy: um servidor que uma das políticas da sua organização recusa. O Claude Code o mostra tanto em claude mcp list quanto em claude mcp get <name>. Um servidor bloqueado por uma allowlist, uma denylist ou outra restrição na configuração MCP gerenciada fica oculto em ambos os comandos em vez de ser mostrado com esse status. Pergunte ao seu administrador qual política bloqueia o servidor.

Aprovações de servidores do projeto e confiança no workspace

claude mcp list e claude mcp get leem aprovações do .mcp.json apenas de arquivos de configuração que não estão no repositório até que você confie no workspace executando claude nele e aceitando a caixa de diálogo de confiança do workspace. Um repositório clonado não pode aprovar seus próprios servidores: enableAllProjectMcpServers ou enabledMcpjsonServers com commit no .claude/settings.json do projeto são ignorados em uma pasta não confiável, e o servidor permanece em ⏸ Pending approval em vez de ser conectado e ter sua integridade verificada.

As aprovações destas fontes ainda se aplicam em uma pasta não confiável:

• seu ~/.claude/settings.json de usuário
• configurações gerenciadas
• configurações passadas com --settings

O Claude Code também aplica aprovações de um .claude/settings.local.json não rastreado, mas executa o git para verificar se o arquivo é rastreado e executa essa verificação apenas em uma pasta confiável. Em uma pasta em que você nunca confiou, o Claude Code aguarda a caixa de diálogo de confiança antes de aplicar as aprovações do arquivo, a menos que a pasta seja sua própria base de configuração: seu diretório pessoal, ou um diretório cujo .claude você definiu como CLAUDE_CONFIG_DIR. Antes da v2.1.207, o Claude Code aplicava aprovações de um .claude/settings.local.json não rastreado mesmo em uma pasta em que você nunca havia confiado.

Uma entrada disabledMcpjsonServers em qualquer arquivo de configuração ainda rejeita o servidor.

Detalhes do status do servidor

Em /mcp, incluindo o menu de um servidor ali, e no gerenciador /plugin, um servidor HTTP ou SSE remoto que você já usou pode mostrar um status cached como cached 2h ago · connects on first use · 5 tools. O Claude Code carregou a lista de ferramentas do servidor a partir do seu cache de descoberta, salvo em uma sessão anterior, em vez de se conectar na inicialização, e o Claude Code conecta o servidor na primeira vez que o Claude chama uma das ferramentas do servidor. As ferramentas ficam disponíveis desde a sua primeira mensagem, então você não precisa fazer nada. O cache de descoberta e seu status cached requerem o Claude Code v2.1.221 ou posterior.

O cache de descoberta fica desativado por padrão, a menos que uma implantação gradual o tenha ativado para sua conta. Defina MCP_DISCOVERY_CACHE=1 para ativá-lo, ou 0 para mantê-lo desativado mesmo quando a implantação o tiver ativado. Antes da v2.1.238, o cache ficava ativado por padrão.

Quando você seleciona Disable ou Clear authentication no menu de um servidor em /mcp, o Claude Code também descarta a entrada de cache desse servidor. Reconnect também a descarta em um servidor conectado ou com falha; em um servidor cached, Reconnect conecta o servidor agora e mantém a entrada. Na próxima vez que o Claude Code se conectar ao servidor após descartar a entrada, ele busca a lista de ferramentas no servidor em vez de no cache.

Falhas de conexão e servidores não configurados

Quando o status de um servidor é ✘ Failed to connect, claude mcp list acrescenta o detalhe da falha a essa linha de status, e claude mcp get <name> o mostra em uma linha Issue:. O detalhe é o status HTTP ou o código de erro, mais qualquer texto de erro que o servidor retornou. A visualização de detalhes do servidor em /mcp inclui o mesmo texto informado pelo servidor em sua linha Issue:.

O Claude Code oculta textos semelhantes a credenciais nesse detalhe e nunca inclui a URL expandida do servidor, que pode conter segredos. O Claude Code não acrescenta nenhum detalhe a um status ✘ Connection error, porque o texto da exceção que ele imprimiria ali pode incorporar essa URL.

Quando você conclui a autenticação em /mcp e a conexão ainda falha com um status HTTP ou um código de erro de transporte, o Claude Code adiciona esse código e a origem da URL do servidor à mensagem que imprime após a tentativa. A origem é o esquema e o host, mais a porta quando a URL especifica uma, como https://mcp.example.com.

• O caminho e a query nunca aparecem nessa mensagem.
• Para um servidor no escopo local, de projeto ou de usuário, ou na configuração MCP gerenciada, a origem mostra o host conforme escrito nessa configuração, então uma referência ${VAR} no host não é expandida na mensagem.
• Para uma falha sem status ou código de erro, o Claude Code mostra o texto do erro sem a origem.

Um servidor remoto cuja configuração tem um url vazio aparece como not configured em /mcp, em claude mcp list e no gerenciador /plugin, e o Claude Code não tenta se conectar a ele. Um plugin pode incluir uma entrada de espaço reservado como esta para um conector que você configura depois, então o Claude Code não a informa como erro ou problema de configuração. A visualização de detalhes do servidor em /mcp exibe No URL configured for this server; defina o url da entrada para conectá-lo.

Avisos de configuração

O Claude Code emite avisos sobre os problemas de configuração abaixo. Cada item diz o que o Claude Code verifica e como eliminar o aviso:

• Espaços em branco ocultos: o Claude Code emite um aviso quando um valor de configuração MCP contém espaços em branco ocultos no início ou no fim, o que costuma vir de colar um token com uma quebra de linha no final. O Claude Code verifica command, url, cada entrada de args e os valores e nomes de chaves em env e headers. O Claude Code mostra o aviso na saída de claude mcp list e em /mcp, nomeando os campos afetados sem repetir seus valores, por exemplo Leading or trailing whitespace in: headers.Authorization. O Claude Code não remove os espaços em branco e usa os valores exatamente como escritos, então edite a configuração para removê-los.
• Mesmo nome em mais de um escopo: se você definir o mesmo nome de servidor em mais de um escopo com endpoints diferentes, o Claude Code emite um aviso sobre o conflito na saída de claude mcp list e em /mcp. O Claude Code armazena logins OAuth por endpoint, então, quando você autentica a definição carregada em um projeto, ainda precisa fazer login separadamente em um projeto onde outra definição é carregada. Mantenha o endpoint que você deseja e remova os outros com claude mcp remove <name> --scope <scope>. No aviso, o Claude Code cita o endpoint de cada escopo conforme escrito na sua configuração, com referências ${VAR} não expandidas, então nunca mostra um valor resolvido como uma chave de API.
• Nomes reservados: o Claude Code reserva os nomes de seus servidores integrados, incluindo workspace, claude-in-chrome, computer-use, Claude Preview e Claude Browser. Se sua configuração definir um servidor com um nome reservado, o Claude Code o ignora no carregamento e mostra um aviso pedindo que você o renomeie. claude mcp add rejeita um nome reservado com um erro. Claude Preview e Claude Browser nomeiam ambos o servidor integrado que o painel de visualização do aplicativo desktop do Claude Code usa.
• Variável de ambiente ausente: se uma referência ${VAR} na configuração de um servidor nomear uma variável que não está definida e não tem :-default, o Claude Code emite um aviso na saída de claude mcp list e em /mcp, nomeando a variável, e ainda carrega o servidor com o texto ${VAR} não expandido. Defina a variável ou adicione um fallback ${VAR:-default}. No url e nos headers de um servidor remoto, algumas variáveis de credenciais são lidas como vazias, sem aviso.

Disponibilidade de ferramentas

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.

Contagens de ferramentas em uma sessão na nuvem

Em uma sessão na nuvem, uma contagem como 3 of 13 tools available significa que o Claude não pode usar as outras 10. Verifique estas causas, entre outras:

• Uma regra de negação no .claude/settings.json do seu repositório nomeia a ferramenta ou todo o seu servidor: remova a regra, se sua sessão ler esse arquivo
• O nome completo da ferramenta tem mais de 128 caracteres: siga as etapas para um nome longo demais
• O servidor lista a ferramenta para sua própria interface e não para o Claude: se você mantém o servidor, adicione model ao _meta.ui.visibility da ferramenta para dar a ferramenta ao Claude. Caso contrário, não há nada a corrigir.

Ferramentas de um servidor que ainda está se conectando

Se sua solicitação precisar de ferramentas de um servidor que ainda está se conectando em segundo plano, o Claude aguarda esse servidor antes de continuar. Como a espera acontece depende da sua configuração:

• Com a pesquisa de ferramentas, o padrão: a espera acontece dentro da chamada ToolSearch.
• Sem a pesquisa de ferramentas: o Claude usa a ferramenta WaitForMcpServers. Configurações sem pesquisa de ferramentas incluem ENABLE_TOOL_SEARCH=false e um modelo anterior ao Claude Opus 4.5, Claude Sonnet 4.5 e Claude Haiku 4.5 no Agent Platform do Google Cloud. Para um gateway ANTHROPIC_BASE_URL, consulte Pesquisa de ferramentas por meio de um gateway de LLM.
• Em uma implantação do Microsoft Foundry hospedada no Azure: o Claude começa pelo caminho da pesquisa de ferramentas em vez de usar WaitForMcpServers, já que o Claude Code só descobre a rejeição do lado do servidor da implantação a partir da API. Depois que o Claude Code muda essa implantação para carregamento antecipado, as ferramentas de um servidor que termina de se conectar ficam disponíveis na próxima requisição do Claude.

Com a pesquisa de ferramentas ativada, quando um servidor termina de se conectar enquanto o Claude está trabalhando, o Claude Code lista os nomes das ferramentas do servidor para o Claude em sua próxima requisição no mesmo turno. O Claude pode então pesquisar e chamar essas ferramentas sem esperar pela sua próxima mensagem.

Depois que você retoma uma sessão, o Claude pode chamar uma ferramenta da conversa salva enquanto o servidor MCP da ferramenta ainda está se conectando. Enquanto o servidor está em sua primeira tentativa de conexão, o Claude Code retém a chamada por até 10 segundos e a executa assim que a ferramenta estiver disponível. Se o servidor não se conectar a tempo, ou já estiver tentando novamente após uma tentativa com falha, a chamada falha com o erro de ferramenta No such tool available.

Desativar um servidor sem removê-lo

Desative um servidor no painel /mcp para impedir que o Claude Code se conecte a ele sem perder sua configuração. O Claude Code continua listando o servidor em /mcp, marcado como desativado.

Quando você alterna um servidor, o Claude Code registra sua escolha por projeto em ~/.claude.json, em uma de duas listas que cobrem conjuntos disjuntos de servidores:

• disabledMcpServers: uma lista de exclusão para servidores configurados pelo usuário, servidores de plugins, servidores que sua organização fornece por meio de configurações gerenciadas, os conectores do claude.ai que o Claude Code busca por conta própria e servidores integrados que são ativados por padrão. O Claude Code não se conecta a um servidor que você lista aqui. Quando você desativa um conector do claude.ai com a alternância por projeto em /mcp descrita em Desativar conectores do claude.ai, o Claude Code o grava nesta lista com seu nome de exibição, por exemplo claude.ai Slack.
• enabledMcpServers: uma lista de inclusão para servidores integrados que são desativados por padrão, como computer-use. O Claude Code se conecta a um servidor desativado por padrão apenas quando você o lista aqui.

O Claude Code consulta exatamente uma das duas listas para cada servidor, então nenhuma lista sobrescreve a outra. Se você adicionar um servidor comum a enabledMcpServers, ou um servidor integrado desativado por padrão a disabledMcpServers, o Claude Code ignora a entrada.

disabledMcpServers e enabledMcpServers não têm relação com enabledMcpjsonServers e disabledMcpjsonServers, que controlam a aprovação de servidores definidos no arquivo .mcp.json de um projeto.

Runtimes de cliente MCP

O Claude Code se conecta a servidores MCP por meio de um de dois runtimes de cliente. O runtime v1 é construído sobre o MCP TypeScript SDK 1.x. O runtime v2 é o mesmo código sobre o MCP TypeScript SDK 2.0, que adiciona a revisão 2026-07-28 do protocolo MCP. O restante desta página se aplica a ambos os runtimes, exceto onde uma seção menciona o runtime v2.

O Claude Code escolhe um runtime cada vez que você o inicia e o mantém até você sair. Em sessões em que ele busca feature flags, ele usa o runtime v2 no Claude Code v2.1.232 ou posterior.

Nas sessões em que não busca feature flags, o Claude Code usa o runtime v2 por padrão no Claude Code v2.1.274 ou posterior:

• Sessões no Amazon Bedrock, Claude Platform on AWS, Agent Platform do Google Cloud ou Microsoft Foundry, a menos que uma plataforma host que incorpora o Claude Code defina CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST
• Sessões conectadas por meio de um Claude apps gateway
• Sessões em que você desativa a telemetria ou a busca de feature flags, por exemplo com DISABLE_TELEMETRY

No v2, o Claude Code também:

• Pergunta aos servidores HTTP, stdio e de conectores do claude.ai se eles oferecem suporte à revisão mais recente e a usa com aqueles que oferecem. Isso inclui os conectores de sessões na nuvem e de Remote Control. O Claude Code se conecta a todos os outros servidores como o v1 faz.
• Recebe notificações list_changed de servidores na revisão mais recente por meio de um stream que mantém aberto.
• Não registra um servidor de canal que se conecta na revisão mais recente, porque essa revisão não pode transportar mensagens de canal.
• Faz falhar um login OAuth MCP cuja resposta de autorização indica um emissor inesperado.
• Envia credenciais OAuth MCP apenas para um endpoint de token servido via HTTPS ou em localhost, 127.0.0.1 ou ::1. O login falha para um servidor cujo endpoint de token é http:// simples em qualquer outro lugar, como um dispositivo na sua rede local. Consulte Refusing to send credentials to non-https token endpoint.

A Anthropic pode manter um servidor específico no protocolo anterior, ou fora desse stream, com uma feature flag que o Claude Code busca. Para escolher o runtime você mesmo, defina MCP_SDK_GENERATION como v1 ou v2.

Para decidir se o Claude Code pergunta aos servidores sobre a revisão mais recente, defina MCP_PROTOCOL_NEGOTIATION como auto ou legacy. Com essa variável não definida, o Claude Code pode deixar de perguntar a um servidor stdio por 7 dias, por exemplo depois que o servidor encerra ao ser perguntado. Para que um servidor atualizado seja perguntado mais cedo, defina auto.

Atualizações dinâmicas de ferramentas

Um servidor MCP pode alterar as ferramentas, prompts ou recursos que oferece enquanto está conectado e enviar uma notificação list_changed. Quando uma chega:

• Em uma sessão interativa no terminal, o Claude Code busca a lista atualizada desse servidor, então você não precisa reconectá-lo.
• No modo não interativo com a flag -p e no Agent SDK, o Claude Code atualiza apenas a lista de ferramentas nessas notificações.

Se uma requisição de atualização falhar, o Claude Code mantém as ferramentas, prompts e recursos descobertos anteriormente no servidor até que uma atualização posterior seja bem-sucedida.

Streams de notificação no runtime v2

No runtime v2, o Claude Code recebe notificações list_changed de um servidor na revisão mais recente do protocolo por meio de um stream que mantém aberto. Quando o stream fecha, o Claude Code o reabre, com dois limites:

• O stream fecha novamente em até 10 segundos: o Claude Code o reabre até três vezes e depois para para essa conexão.
• O stream permanece aberto por mais de 10 segundos e depois fecha, como costuma acontecer com streams para hosts serverless: após cinco reaberturas em uma hora, o Claude Code aguarda cerca de seis horas antes da próxima.

Até que o stream seja reaberto, você mantém as últimas ferramentas, prompts e recursos buscados do servidor. Para obter suas alterações mais cedo, reconecte o servidor em /mcp.

Reconexão automática

O Claude Code reconecta um servidor remoto que cai no meio da sessão e tenta novamente a primeira conexão de um servidor HTTP ou SSE após um erro transitório. Para um servidor stdio, consulte Servidores stdio que encerram ou não iniciam.

Quedas de um servidor remoto no meio da sessão

O Claude Code primeiro tenta reconectar um servidor remoto que caiu até cinco vezes com backoff exponencial, começando com um atraso de um segundo e dobrando-o a cada vez:

• Em uma sessão interativa: /mcp mostra o servidor como pendente enquanto o Claude Code reconecta. Após cinco tentativas com falha, o Claude Code marca o servidor como com falha, ou como precisando de autenticação quando o servidor precisa ser autorizado novamente. Quando marca o servidor como com falha, você vê uma notificação MCP server "<name>" disconnected · open /mcp to reconnect. Você pode tentar novamente manualmente em /mcp.
• Em execuções claude -p e sessões do Agent SDK: o Claude Code faz as mesmas cinco tentativas, sem um painel /mcp para exibi-las. Se todas as cinco falharem, a execução continua sem as ferramentas do servidor:
  • Após um erro transitório, como uma resposta 5xx ou um timeout: o Claude Code continua tentando novamente um servidor HTTP ou SSE em segundo plano. As novas tentativas duram até cerca de meia hora, e as ferramentas do servidor voltam a ficar disponíveis quando uma delas se conecta. Até lá, uma sessão do Agent SDK informa o status failed, e seu código pode reconectar o servidor. Para reconectá-lo em claude -p, inicie a execução novamente.
  • Quando o servidor precisa que você faça login novamente: o Claude Code para de tentar novamente, e uma sessão do Agent SDK informa o status do servidor como needs-auth. Faça login com claude mcp login <name> no seu shell. Em seguida, inicie a execução novamente ou, em uma sessão do Agent SDK, reconecte o servidor.

Primeiras conexões com falha

Quando a primeira conexão de um servidor HTTP ou SSE falha com um erro transitório, como uma resposta 5xx, uma conexão recusada ou um timeout, o Claude Code tenta novamente até três vezes. Se a conexão ainda falhar, o Claude Code marca o servidor como com falha.

Essas novas tentativas não se aplicam nestes casos:

• A primeira conexão de um servidor stdio. Para tentar novamente, consulte Servidores stdio que encerram ou não iniciam
• A primeira conexão de um servidor WebSocket. Para tentar novamente em uma sessão interativa no terminal, selecione Reconnect no menu do servidor em /mcp
• Um erro de autenticação ou de não encontrado, porque requer uma alteração de configuração para ser resolvido. Quando um headersHelper é a única fonte do cabeçalho Authorization do servidor, o Claude Code tenta novamente mesmo assim após um erro de autenticação, porque executa o helper novamente a cada tentativa e pode obter uma credencial nova

Servidores stdio que encerram ou não iniciam

Para iniciar um servidor stdio novamente, leia a coluna que corresponde ao que aconteceu com ele. Encontre sua linha pela forma como você executa o Claude Code: uma sessão interativa, uma execução claude -p ou uma sessão do Agent SDK.

Requisições de descoberta com falha

Depois que um servidor se conecta, o Claude Code envia a ele requisições de descoberta de capacidades como tools/list, prompts/list e resources/list. O Claude Code tenta novamente essas requisições até três vezes com um backoff curto após um erro transitório de rede ou de servidor. Ele não tenta novamente após erros de autenticação, respostas 4xx ou timeouts de requisição.

Tentar novamente servidores com falha por conta própria

Para tentar novamente todos os servidores que falharam ou precisam de autenticação, execute /mcp reconnect all no prompt do Claude Code em uma sessão interativa no terminal. Isso requer o Claude Code v2.1.284 ou posterior. Versões anteriores imprimem MCP server "all" not found.

Como o Claude fica sabendo que um servidor falhou

Se o Claude Code informa o Claude sobre um servidor configurado que não conseguiu se conectar depende da pesquisa de ferramentas, que está ativada por padrão:

• Com a pesquisa de ferramentas, o Claude Code informa ao Claude qual servidor falhou e seu erro de conexão, para que o Claude relate a falha de conexão em sua resposta. O Claude Code inclui as mesmas informações nos resultados de ToolSearch que não encontram nenhuma ferramenta correspondente.
• Em qualquer configuração sem pesquisa de ferramentas, o Claude Code não informa ao Claude sobre conexões de servidor com falha.

Enviar mensagens com canais

Um servidor MCP também pode enviar mensagens diretamente para sua sessão para que o Claude possa reagir a eventos externos, como resultados de CI, alertas de monitoramento ou mensagens de chat. Para habilitar isso, seu servidor declara a capacidade claude/channel e você o habilita com a flag --channels na inicialização. Consulte Channels para usar um canal com suporte oficial, ou Referência de Channels para criar o seu próprio.

No runtime v2, um servidor de canal que negocia a revisão 2026-07-28 do protocolo MCP não pode entregar mensagens de canal, então o Claude Code não o registra como canal. Um servidor de canal que não oferece suporte a essa revisão se conecta no handshake anterior e se registra como antes.

O Claude Code pergunta aos servidores stdio sobre essa revisão por padrão. Para manter um servidor de canal stdio no handshake anterior, defina MCP_PROTOCOL_NEGOTIATION como legacy, o que mantém todos os servidores nele.

[!TIP]

Dicas:

• Use a flag -s ou --scope para especificar onde a configuração é armazenada:
  • local (padrão): disponível apenas para você no projeto atual
  • project: compartilhado com todos no projeto por meio do arquivo .mcp.json
  • user: disponível para você em todos os projetos
• Defina variáveis de ambiente com as flags -e ou --env (por exemplo, -e KEY=value)
• As flags --transport e --header também aceitam as formas curtas -t e -H
• Configure o timeout de inicialização do servidor MCP usando a variável de ambiente MCP_TIMEOUT (por exemplo, MCP_TIMEOUT=10000 claude define um timeout de 10 segundos)
• Defina um timeout de execução de ferramentas por servidor adicionando um campo timeout em milissegundos à entrada desse servidor no .mcp.json, por exemplo "timeout": 600000 para dez minutos. Isso sobrescreve a variável de ambiente MCP_TOOL_TIMEOUT apenas para esse servidor
• O Claude Code exibe um aviso quando a saída de uma ferramenta MCP excede 10.000 tokens e limita a saída a 25.000 tokens por padrão. Para alterar o limite de tokens, defina a variável de ambiente MAX_MCP_OUTPUT_TOKENS, por exemplo MAX_MCP_OUTPUT_TOKENS=50000. O limite do aviso é fixo. A menos que o servidor aumente o limite próprio de uma ferramenta, resultados de texto bem-sucedidos com mais de 50.000 caracteres são salvos em um arquivo independentemente dessa variável. Consulte Limites e avisos de saída MCP
• Use /mcp para se autenticar em servidores remotos que exigem autenticação OAuth 2.0

Limites de tempo em chamadas de ferramentas MCP

Para limitar por quanto tempo uma chamada de ferramenta MCP pode ser executada:

• Por servidor: adicione um campo timeout em milissegundos à entrada de configuração desse servidor
• Para todos os servidores: defina MCP_TOOL_TIMEOUT

O timeout por servidor é um limite rígido de tempo real por chamada de ferramenta, e notificações de progresso do servidor não o estendem. Valores abaixo de 1000 são ignorados e recorrem a MCP_TOOL_TIMEOUT, ou ao seu padrão de cerca de 28 horas quando essa variável não está definida. Para um servidor HTTP, SSE ou de conector do claude.ai, também existe um segundo temporizador, por requisição, que cobre cada requisição até o primeiro byte da resposta do servidor. O Claude Code define esse temporizador como o maior de três valores: 60 segundos, o timeout de ferramenta que se aplica ao servidor e MCP_TIMEOUT. O padrão de 28 horas de um MCP_TOOL_TIMEOUT não definido não entra nessa comparação, e um valor abaixo de 60 segundos não encurta o temporizador. Servidores stdio e WebSocket não têm temporizador por requisição.

Um timeout por servidor de pelo menos 1000 também atua como piso para o timeout de inatividade descrito abaixo: o Claude Code nunca interrompe as chamadas de ferramenta desse servidor por inatividade antes do timeout por servidor.

Uma chamada de ferramenta para um servidor MCP que não envia nenhuma resposta nem notificação de progresso durante a janela de inatividade é interrompida com um erro em vez de aguardar o limite de tempo real. O timeout de inatividade se aplica a todos os tipos de servidor, exceto servidores de IDE e servidores SDK em processo. A janela de inatividade tem como padrão cinco minutos para servidores HTTP, SSE, WebSocket e de conector do claude.ai, e 30 minutos para servidores stdio.

Defina a variável de ambiente CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT em milissegundos para alterar a janela de inatividade, ou defina-a como 0 para desativar a verificação.

Esses timeouts limitam por quanto tempo uma chamada pode ser executada, nem sempre por quanto tempo ela bloqueia a sessão: uma chamada da conversa principal que passa de dois minutos é movida primeiro para uma tarefa em segundo plano. Consulte Envio automático de chamadas de ferramentas longas para segundo plano.

Envio automático de chamadas de ferramentas longas para segundo plano

Se a visualização de detalhes de uma chamada em segundo plano em /tasks mostrar runs on the server; survives exiting this session, consulte Tarefas MCP executadas no servidor.

Uma chamada de ferramenta MCP na conversa principal que ainda está em execução após dois minutos é movida para uma tarefa em segundo plano em vez de bloquear a sessão. O Claude recebe o ID da tarefa imediatamente e continua trabalhando, e o resultado chega como uma notificação de tarefa quando a chamada é concluída.

A tarefa aparece em /tasks, onde você também pode interrompê-la, e ela não sobrevive ao encerramento da sessão. A entrada da tarefa mostra o progresso mais recente informado pelo servidor. Se você interromper a tarefa, o Claude Code cancela a chamada e informa ao Claude que nenhum resultado virá. Interromper não garante que o servidor pare: ele pode já ter feito parte do trabalho, ou ainda pode concluí-lo.

Os limites por chamada continuam se aplicando enquanto a chamada é executada em segundo plano: o limite de tempo real definido pelo timeout por servidor ou por MCP_TOOL_TIMEOUT, e o timeout de inatividade definido por CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT.

Para alterar ou desativar o envio automático para segundo plano:

• Defina a variável de ambiente CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS em milissegundos para alterar o limite, ou defina-a como 0 para desativar o envio automático para segundo plano. Com 0, o Claude também aguarda tarefas MCP em uma sessão interativa
• Defina CLAUDE_CODE_DISABLE_BACKGROUND_TASKS como 1 para desativar o envio automático para segundo plano e os comandos em segundo plano

Algumas chamadas nunca são movidas para segundo plano:

• Chamadas de subagentes; o Claude Code envia para segundo plano apenas chamadas da conversa principal
• Chamadas para servidores de IDE
• Chamadas no modo não interativo, a menos que CLAUDE_AUTO_BACKGROUND_TASKS esteja definida como 1, já que uma execução única pode terminar antes de o resultado chegar

Uma chamada que aguarda uma caixa de diálogo de elicitação aberta não é enviada para segundo plano enquanto a caixa de diálogo estiver aberta; o servidor está bloqueado aguardando sua entrada, não lento, então o Claude Code adia a mudança até que a caixa de diálogo seja fechada.

Tarefas MCP executadas no servidor

Uma tarefa MCP é um trabalho longo, como uma exportação de relatório ou um build, que um servidor MCP executa por conta própria usando a extensão de tarefas MCP. A chamada de ferramenta do Claude retorna assim que o servidor aceita o trabalho, então o Claude continua trabalhando, a menos que você faça o Claude aguardar. Quando o trabalho termina, a transcrição informa isso e o Claude recebe o resultado. Peça-o ao Claude.

Enquanto isso, o rodapé mostra uma contagem como 1 MCP task, e o Claude Code acompanha a tarefa verificando seu status com o servidor. Uma tarefa em um servidor remoto continua em execução depois que você sai. Para acompanhá-la novamente, retome a mesma sessão.

[!NOTE]

As tarefas MCP estão em beta público na CLI do Claude Code e requerem o Claude Code v2.1.304 ou posterior. O que uma chamada precisa para se tornar uma tarefa MCP lista as sessões e os servidores que as recebem.

Interromper uma tarefa MCP ou obter seu resultado

Para interromper uma tarefa em execução, selecione-a em /tasks e pressione x, ou peça ao Claude que faça isso. O Claude Code para de acompanhar a tarefa e pede ao servidor que a cancele, embora o servidor ainda possa concluí-la. Reconecte primeiro um servidor desconectado em /mcp; caso contrário, nenhuma requisição de cancelamento é enviada e o Claude Code esquece a tarefa e não pode acompanhá-la novamente. Pressionar Esc não interrompe uma tarefa em segundo plano.

Quando a tarefa termina, uma linha como esta aparece na transcrição:

MCP task <server task id> (<server>/<tool>) completed.

O resultado vai para o Claude, não para a transcrição, então peça-o ao Claude. Se o Claude estiver ocioso quando o resultado chegar, o Claude começa a trabalhar nele sem que você peça.

Responder a uma pergunta de uma tarefa MCP

Uma tarefa em execução pode abrir uma caixa de diálogo de elicitação para pedir sua entrada. Enquanto /tasks está aberto, a caixa de diálogo fica oculta, então feche /tasks para responder. Recusar ou pressionar Esc é uma resposta ao servidor, que então decide se a tarefa continua.

Em uma sessão não interativa, o Claude Code pede ao servidor que cancele uma tarefa que solicita entrada, sem executar seus hooks Elicitation nem chamar o callback onElicitation do Agent SDK.

Sair, limpar ou retomar enquanto uma tarefa MCP é executada

Uma tarefa em um servidor remoto continua em execução depois que você sai. O processo de um servidor stdio para quando o Claude Code sai, embora suas tarefas mostrem runs on the server; survives exiting this session em /tasks. A menos que a documentação desse servidor diga que o trabalho sobrevive ao processo, deixe essas tarefas terminarem ou interrompa-as em /tasks antes.

O que uma chamada precisa para se tornar uma tarefa MCP

Uma chamada de ferramenta se torna uma tarefa MCP somente quando todas estas condições são atendidas:

• O servidor oferece suporte a tarefas
• O servidor é um servidor HTTP, stdio ou de conector do claude.ai conectado na revisão de protocolo 2026-07-28. Definir MCP_SDK_GENERATION=v1 ou MCP_PROTOCOL_NEGOTIATION=legacy exclui isso
• A sessão busca feature flags, portanto não em um provedor terceiro como o Amazon Bedrock, nem com a telemetria ou a busca de flags desativada
• A Anthropic ativou as tarefas MCP para o seu tipo de sessão. Na v2.1.304 ou posterior, isso abrange sessões da CLI no terminal, sessões do Agent SDK e execuções do GitHub Actions. Outras superfícies, como a extensão do VS Code e o aplicativo desktop, não têm tarefas MCP
• A chamada vem da conversa principal, não de um subagente
• Ou a sessão é interativa, ou uma sessão do Agent SDK ou uma execução claude -p lendo --input-format stream-json tem:
  • CLAUDE_AUTO_BACKGROUND_TASKS em 1
  • CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND diferente de 1
  • CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS diferente de 0

Qualquer outra chamada é uma chamada de ferramenta comum, e Envio automático de chamadas de ferramentas longas para segundo plano indica quais delas são movidas para segundo plano.

Mantenha a entrada de uma sessão do Agent SDK ou stream-json aberta, porque a execução não aguarda tarefas MCP depois que a entrada é fechada. Uma execução única claude -p "<prompt>" não recebe tarefas MCP.

Mensagens de status em uma tarefa MCP

Estas mensagens, na entrada /tasks de uma tarefa ou em sua linha final na transcrição, significam que o Claude Code não consegue alcançar o servidor ou a tarefa. Enquanto uma delas aparece em /tasks, o trabalho ainda pode estar em execução: o Claude Code não interfere nele e continua verificando. A mensagem de 300s e as de configuração permanecem na entrada mesmo depois que o contato é restabelecido.

Limites de tempo em tarefas MCP

Por padrão, uma tarefa em segundo plano não tem limite de tempo do Claude Code. Os limites de tempo de chamadas de ferramenta, incluindo o limite de tempo real e o timeout de inatividade, se aplicam até que o servidor responda à chamada com a tarefa. Se você fizer o Claude aguardar, eles se aplicam à tarefa inteira. Verificações de status respondidas contam como atividade para o timeout de inatividade.

Fazer o Claude aguardar o resultado de uma tarefa MCP

Para fazer o Claude aguardar o resultado de uma tarefa em uma sessão interativa, defina uma de duas variáveis de ambiente, por exemplo no bloco env do settings.json:

• CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS definida como 0: o Claude aguarda cada chamada de ferramenta MCP até que a chamada termine
• CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND definida como 1: o Claude aguarda o resultado de uma tarefa. Enquanto o envio automático para segundo plano estiver ativado, ele move a chamada após dois minutos por padrão, então tarefas curtas terminam no lugar e as longas não bloqueiam você. A chamada movida é uma chamada em segundo plano comum, e não uma tarefa MCP. Ela não sobrevive ao encerramento da sessão

Enquanto o Claude aguarda, pressionar Esc ou atingir o limite de tempo real ou o timeout de inatividade encerra a chamada, e o Claude Code pede ao servidor que cancele a tarefa.

Se você definir CLAUDE_CODE_DISABLE_BACKGROUND_TASKS como 1 ou iniciar no modo bare, isso por si só não faz o Claude aguardar tarefas MCP. Este exemplo define CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS como 0, então o Claude aguarda cada chamada de ferramenta MCP:

{
  "env": {
    "CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS": "0"
  }
}

Tarefas MCP para autores de servidores

Se você cria um servidor MCP, pode responder a um tools/call de longa duração com uma tarefa. A extensão de tarefas MCP define as mensagens que você envia. Em uma conexão na revisão de protocolo 2026-07-28, cada requisição carrega as capacidades de cliente do Claude Code em params._meta["io.modelcontextprotocol/clientCapabilities"], com "io.modelcontextprotocol/tasks": {} em extensions. Uma requisição tools/call que não pode se tornar uma tarefa omite essa extensão.

Responder à chamada com uma tarefa

Responda com uma tarefa somente quando a requisição carregar a extensão; caso contrário, a chamada falha com o erro de ferramenta Unsupported result type 'task' for tools/call. A chamada falha da mesma forma se sua resposta não tiver taskId ou não tiver um status válido. O objeto da tarefa é o result JSON-RPC da sua resposta a tools/call, não precisa de um array content e aqui inclui os campos opcionais statusMessage e pollIntervalMs:

{
  "resultType": "task",
  "taskId": "build-7f3a9c2e",
  "status": "working",
  "statusMessage": "Compiling, 40 of 212 files done",
  "createdAt": "2026-10-22T14:03:07Z",
  "lastUpdatedAt": "2026-10-22T14:03:07Z",
  "ttlMs": null,
  "pollIntervalMs": 5000
}

O Claude Code aceita uma resposta de tarefa que omite createdAt, lastUpdatedAt ou ttlMs, ou que define pollIntervalMs como null. Antes da v2.1.317, a chamada falhava com o erro Unsupported result type. Para funcionar também com essas versões, envie os três campos que a extensão de tarefas exige e envie pollIntervalMs como um número ou não o envie.

Em um servidor HTTP ou de conector do claude.ai, a resposta de tarefa precisa começar dentro do temporizador por requisição, então aceite o trabalho e responda primeiro, e depois faça o trabalho.

Informar status, resultados e perguntas

Logo após a resposta de tarefa, o Claude Code envia tasks/get com { "taskId": ... } e depois o repete uma vez por intervalo de polling. A extensão de tarefas exige que sua resposta carregue "resultType": "complete" junto com taskId, status, createdAt, lastUpdatedAt e ttlMs. ttlMs pode ser null, e statusMessage e pollIntervalMs são opcionais. Este exemplo informa que o build foi concluído:

{
  "resultType": "complete",
  "taskId": "build-7f3a9c2e",
  "status": "completed",
  "createdAt": "2026-10-22T14:03:07Z",
  "lastUpdatedAt": "2026-10-22T14:09:41Z",
  "ttlMs": null,
  "result": {
    "content": [{ "type": "text", "text": "Build succeeded: 212 files, 0 warnings" }]
  }
}

Servidores MCP fornecidos por plugins

Plugins podem incluir servidores MCP que fornecem ferramentas e integrações quando você habilita o plugin.

Como funcionam os servidores MCP de plugins:

• Os plugins definem servidores MCP em .mcp.json na raiz do plugin ou inline em plugin.json
• Quando você habilita um plugin, o Claude Code inicia seus servidores MCP automaticamente
• O Claude Code oferece as ferramentas MCP de plugins junto com as ferramentas MCP configuradas manualmente
• Você adiciona e remove servidores de plugins instalando ou desinstalando o plugin, não com comandos /mcp. Você ainda pode desativar um servidor de plugin instalado em /mcp, o que impede o Claude Code de se conectar a ele sem remover o plugin

Exemplo de configuração MCP de plugin:

Em .mcp.json na raiz do plugin:

{
  "mcpServers": {
    "database-tools": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_URL": "${DB_URL}"
      }
    }
  }
}

Ou inline em plugin.json:

{
  "name": "my-plugin",
  "mcpServers": {
    "plugin-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "8080"]
    }
  }
}

Recursos MCP de plugins:

• Ciclo de vida automático: os servidores se conectam e desconectam nestes momentos:
  • Na inicialização da sessão, o Claude Code conecta automaticamente os servidores dos plugins habilitados. Em /mcp, um servidor de plugin remoto (HTTP ou SSE) que você já usou antes pode mostrar o status cached em vez disso; o Claude Code o conecta quando o Claude chama uma de suas ferramentas pela primeira vez. Quando a conexão de um servidor de plugin stdio falhou há menos de 15 minutos, o Claude Code ignora a conexão
  • Se você habilitar ou desabilitar um plugin durante uma sessão, o Claude Code conecta ou desconecta seus servidores MCP quando a alteração é aplicada. Aplicar alterações de plugins sem reiniciar descreve quando isso acontece. Em uma sessão sem um terminal interativo, /reload-plugins não conecta nem desconecta servidores MCP de plugins; essas alterações entram em vigor na sua próxima sessão
  • Quando você recarrega, o Claude Code mantém as conexões ativas dos servidores de plugins cuja configuração não mudou, e faz o mesmo quando você substitui a lista de servidores MCP da sessão a partir do Agent SDK sem nomeá-los
  • Quando você move a sessão com /cd na v2.1.246 ou posterior, o Claude Code conecta os servidores dos plugins que as configurações do novo diretório habilitam e desconecta os servidores dos plugins que não estão mais habilitados, então você não precisa executar /reload-plugins após a mudança
  • Em sessões na nuvem, uma chamada MCP para um servidor de plugin que ainda não está conectado, como logo após uma sessão ociosa ser retomada, inicia o servidor sob demanda e aguarda a conexão
• Placeholders de caminho: ${CLAUDE_PLUGIN_ROOT} resolve para o diretório de instalação do plugin, ${CLAUDE_PLUGIN_DATA} para seu diretório de estado persistente e ${CLAUDE_PROJECT_DIR} para a raiz estável do projeto. A substituição se aplica a:
  • Servidores stdio: command, args, env
  • Servidores http, sse e ws: url, headers e headersHelper
• Acesso ao ambiente do usuário: acesso às mesmas variáveis de ambiente que os servidores configurados manualmente
• Vários tipos de transporte: suporte para transportes stdio, SSE, HTTP e WebSocket, embora o suporte a transportes possa variar conforme o servidor

Os servidores de plugins aparecem em /mcp com indicadores mostrando que vêm de plugins.

claude mcp get oculta os valores configurados para o servidor stdio ou WebSocket de um plugin, porque eles podem conter credenciais:

• Servidor stdio: exibe Command: stdio, uma linha Args: vazia e cada variável de ambiente como NAME=[REDACTED]
• Servidor WebSocket: exibe URL: ws e cada header como <name>: [REDACTED], e claude mcp list mostra ws no lugar da URL

Para ver o que o plugin configurou, encontre o plugin no disco e leia seu .mcp.json ou plugin.json.

Nomes de ferramentas MCP de plugins:

As ferramentas de um servidor MCP incluído em um plugin contêm tanto o nome do plugin quanto a chave do servidor em seu nome chamável. A forma completa é mcp__plugin_<plugin-name>_<server-name>__<tool-name>, em que qualquer caractere fora de A-Z, a-z, 0-9, _ e - é substituído por _. Para o servidor database-tools incluído em um plugin chamado my-plugin, uma ferramenta query pode ser chamada como:

mcp__plugin_my-plugin_database-tools__query

Use esse nome completo ao referenciar a ferramenta em regras de permissão, na lista allowed-tools de uma skill, no campo tools de um subagente ou em um matcher de hook. Um matcher de hook escrito com base apenas na chave do servidor, como mcp__database-tools__.*, nunca é acionado para um servidor incluído em um plugin.

O próprio servidor é registrado com o nome com escopo plugin:<plugin-name>:<server-name>, como plugin:my-plugin:database-tools. Use esse nome onde se espera o nome de um servidor configurado, como no campo server de um hook mcp_tool.

Consulte a referência de componentes de plugins para obter detalhes sobre como incluir servidores MCP em plugins.

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 ou fornecer servidores para cada usuário 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.

[!NOTE]

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.

# Adicionar um servidor com escopo local (padrão)
claude mcp add --transport http stripe https://mcp.stripe.com

# Especificar explicitamente escopo local
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

O comando escreve o servidor na entrada do seu projeto atual dentro de ~/.claude.json. O exemplo abaixo mostra o resultado quando você o executa de /path/to/your/project:

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "stripe": {
          "type": "http",
          "url": "https://mcp.stripe.com"
        }
      }
    }
  }
}

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. Quando você adiciona um servidor com escopo de projeto, Claude Code cria ou atualiza automaticamente este arquivo com a estrutura de configuração apropriada. Verifique .mcp.json no controle de versão para que todos na sua equipe obtenham as mesmas ferramentas e serviços MCP.

# Adicionar um servidor com escopo de projeto
claude mcp add --transport http shared-server --scope project https://example.com/mcp

O arquivo .mcp.json resultante segue um formato padronizado:

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

Por razões de segurança, Claude Code solicita aprovação em sessões interativas antes de usar servidores com escopo de projeto de arquivos .mcp.json. Para redefinir essas escolhas de aprovação, execute claude mcp reset-project-choices.

Em execuções claude -p, sessões do Agent SDK e sessões na nuvem fora das threads de um projeto, Claude Code não pode mostrar esse prompt: ele carrega servidores com escopo de projeto sem perguntar. Claude Code também ignora o prompt em uma sessão que você inicia no modo bypassPermissions com skipDangerousModePermissionPrompt definido em suas configurações de usuário ou em configurações gerenciadas. Para manter um servidor fora mesmo assim:

• Adicione-o a disabledMcpjsonServers, que o bloqueia em todos os modos de permissão.
• Exclua as configurações do projeto inteiramente com --setting-sources ou a opção settingSources do SDK.
• Inicie a sessão com --strict-mcp-config. Claude Code então usa apenas os servidores MCP que você passa com --mcp-config. Ignorar o prompt de aprovação para os servidores com escopo de projeto que Claude Code não está carregando requer Claude Code v2.1.246 ou posterior; antes de v2.1.246, uma sessão estrita ainda aguardava aprovação para eles, o que deixava sessões em segundo plano aguardando na inicialização. Veja Controle exclusivo com managed-mcp.json para o que o sinalizador faz sob um arquivo MCP gerenciado.

Aprovações de servidor de projeto e confiança do espaço de trabalho aborda como as aprovações confirmadas no repositório interagem com a confiança do espaço de trabalho.

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.

# Adicionar um servidor de usuário
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

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.

1. Escopo local
2. Escopo de projeto
3. Escopo de usuário
4. Servidores fornecidos por plugins
5. Conectores claude.ai

Claude Code corresponde duplicatas nos três escopos por nome. Ele corresponde plugins e conectores por endpoint, então um que aponta para a mesma URL ou comando que um servidor acima é tratado como uma duplicata.

Duas grafias de URL contam como o mesmo endpoint quando diferem apenas na letra maiúscula do esquema ou host, a porta padrão do esquema, como :443 em https, ou uma barra final. Um caminho diferente, string de consulta, userinfo ou porta não padrão torna dois servidores diferentes.

Um servidor que sua organização fornece através da configuração gerenciada managedMcpServers classifica-se acima de todos esses, então quando um deles o duplica, Claude Code conecta a definição da organização. Requer Claude Code v2.1.259 ou posterior.

Se você abrir uma sessão local na guia Code do aplicativo Desktop com o mesmo nome de servidor stdio no nível superior de ~/.claude.json (escopo de usuário) e em .mcp.json, a guia Code usa a definição ~/.claude.json.

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.

Você pode referenciar uma variável de ambiente no valor command, args, env, url ou headers de um servidor, em qualquer uma de duas formas:

• ${VAR}: expande para o valor da variável de ambiente VAR
• ${VAR:-default}: expande para o valor de VAR se VAR estiver definida, ou para default se não estiver definida

Exemplo com expansão de variável

Nesta entrada de servidor, a URL é o valor de API_BASE_URL seguido de /mcp, com https://api.example.com como padrão, e a chave de API vem de API_KEY:

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

Variáveis não definidas sem um padrão

Se uma variável de ambiente referenciada não estiver definida e não tiver um valor padrão, a configuração ainda é carregada: Claude Code relata um aviso de variável ausente para esse servidor na saída claude mcp list e usa o texto ${VAR} não expandido como está. Defina a variável ou adicione um fallback :-default para que o servidor inicie com o valor que você pretende. Na url e nos headers de um servidor remoto, algumas variáveis de credencial leem como vazias em vez disso, sem aviso.

Variáveis definidas como uma string vazia

Se você definir uma variável como uma string vazia, ela conta como definida, então uma referência ${VAR:-default} expande para a string vazia em vez de para default. Com o servidor de exemplo, se você definir API_BASE_URL como uma string vazia, sua url se torna /mcp e claude mcp list relata 'url' is not a valid URL. Para usar o padrão, remova a definição da variável em vez de defini-la como uma string vazia.

Variáveis de credencial que leem como vazias

Na url e nos headers de um servidor remoto, Claude Code lê variáveis de credencial do seu ambiente como vazias em vez de expandi-las. Isso impede que a .mcp.json de um projeto ou um plugin envie suas credenciais Claude Code ou de provedor de nuvem para um servidor que ele nomeia. Se você escrever Bearer ${ANTHROPIC_AUTH_TOKEN}, o servidor recebe Bearer sem credencial e rejeita a requisição, geralmente com um 401. Claude Code relata isso como uma conexão falhada.

Os nomes cobertos são:

• Credenciais próprias do Claude Code, como ANTHROPIC_API_KEY e ANTHROPIC_AUTH_TOKEN
• Credenciais do seu provedor de nuvem, como AWS_BEARER_TOKEN_BEDROCK
• Outras credenciais que seu ambiente carrega, como HTTPS_PROXY e NPM_TOKEN

Um nome coberto lê como vazio independentemente de você ter definido a variável, e um fallback :-default nele é ignorado. Uma URL base do provedor como ANTHROPIC_BASE_URL ainda expande, então "url": "${ANTHROPIC_BASE_URL}/mcp" funciona, a menos que o valor da URL em si incorpore uma credencial como um nome de usuário e senha.

Um nome fora deste conjunto, como API_KEY, expande conforme escrito. Para dar ao servidor uma das credenciais cobertas, copie-a para uma variável com um nome de sua escolha e referencie esse nome em vez disso.

Quando a url ou os headers de um servidor remoto referenciam uma variável coberta que você definiu, Claude Code a nomeia em uma linha de log de depuração. Para ler a linha, execute claude --debug-file /tmp/claude-debug.log e procure nesse arquivo por never expanded toward a remote server.

Como referências aparecem em /mcp e saída de CLI

Para um servidor no escopo local, de projeto ou de usuário, as seguintes superfícies mostram uma referência ${VAR} por nome em vez de seu valor resolvido:

• A URL ou linha de comando na visualização de detalhes /mcp de um servidor
• Saída de claude mcp list e claude mcp get

A visualização de detalhes /mcp mostra referências desta forma em Claude Code v2.1.268 ou posterior.

Para um servidor que sua organização fornece através da configuração managedMcpServers, essas superfícies mostram apenas o host da URL.

Para verificar o que claude mcp list, claude mcp get e /mcp mostram quando uma conexão falha, veja Detalhe do status do servidor.

Exemplos práticos

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:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

Substitua YOUR_GITHUB_PAT pelo seu token de acesso pessoal. O comando claude mcp add salva a configuração sem validar credenciais, portanto um valor de espaço reservado é aceito aqui, mas o servidor falha ao conectar mais tarde. Para verificar a conexão, execute /mcp e verifique se a linha do servidor mostra uma marca de seleção. Um servidor com credenciais inválidas mostra um ✘ em vez disso, e seu detalhe da falha inclui o status HTTP que o servidor retornou, como um 401.

Então trabalhe com GitHub:

Revise o PR #456 e sugira melhorias

Crie um novo problema para o bug que acabamos de encontrar

Mostre-me todos os PRs abertos atribuídos a mim

Exemplo: Consultar seu banco de dados PostgreSQL

DBHub, o pacote @bytebase/dbhub, é um servidor MCP que conecta Claude a um banco de dados relacional através da string de conexão que você passa em --dsn. Use um usuário de banco de dados somente leitura na string de conexão para que as consultas que Claude executa não possam modificar dados:

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

Para confirmar que o servidor inicia, execute /mcp e verifique se a linha db mostra uma marca de seleção.

Então consulte seu banco de dados naturalmente:

Qual é nossa receita total este mês?

Mostre-me o esquema para a tabela de pedidos

Encontre clientes que não fizeram uma compra em 90 dias

Autenticar com servidores MCP remotos

Muitos servidores MCP baseados em nuvem exigem autenticação. O Claude Code oferece suporte a OAuth 2.0 para conexões seguras.

O Claude Code marca um servidor remoto como precisando de autenticação quando o servidor responde com 401 Unauthorized ou 403 Forbidden. O que o Claude Code mostra depende do servidor:

• Para um servidor no qual você ainda não fez login, qualquer um dos códigos de status o sinaliza em /mcp para que você possa concluir o fluxo OAuth.
• Para um conector do claude.ai, um 401 causado pelo claude.ai rejeitar seu token de sessão não sinaliza o conector, porque autorizar o conector novamente não pode corrigir seu login. Em vez disso, o Claude Code mostra o estado de token de sessão rejeitado.
• Para um servidor cujo cabeçalho Authorization você configurou, em headers ou por meio de um headersHelper, um 401 ou 403 durante a conexão não sinaliza o servidor, porque a credencial a ser corrigida é aquela que você configurou. Em vez disso, o Claude Code informa que a conexão falhou. Se você definiu esse cabeçalho a partir de uma referência ${VAR}, verifique se essa variável é uma das que o Claude Code lê como vazia.
• Para um conector entregue a uma sessão na nuvem, o Claude Code não executa um fluxo de login, porque o proxy da sessão se autentica no conector com a autorização que você concedeu no claude.ai. Quando um conector ali precisar ser autorizado novamente, reconecte-o em claude.ai/customize/connectors em vez de fazê-lo a partir da sessão.

Quando um servidor OAuth no qual você já fez login rejeita seu token armazenado com 401 Unauthorized, o Claude Code se reconecta com ou sem um novo token:

• Seu login armazenado tem um refresh token: ele atualiza o token, reconecta e tenta novamente a requisição uma vez. O servidor é sinalizado em /mcp somente se essa nova tentativa também falhar.
• Seu login armazenado não tem refresh token: ele se conecta uma vez sem o token. Se o servidor responder, suas ferramentas funcionam enquanto você está desconectado, e o token rejeitado é excluído. Se o servidor também rejeitar essa conexão, o /mcp mostra que o servidor precisa de autenticação.

Em uma execução de claude -p ou do Agent SDK no macOS, uma requisição que o Claude Code enviou enquanto não conseguia ler seu token armazenado falha com um erro de credenciais armazenadas.

Quando o servidor rejeita o refresh token armazenado, o Claude Code mostra imediatamente um aviso apontando para /mcp. Abra /mcp e selecione Re-authenticate no servidor para fazer login novamente antes que a próxima chamada de ferramenta falhe.

Um servidor personalizado que retorna um cabeçalho WWW-Authenticate apontando para seu servidor de autorização recebe a mesma descoberta automática que qualquer outro servidor remoto.

O Claude Code também mostra um aviso na inicialização quando um ou mais servidores configurados precisam de autenticação, para que você não precise abrir /mcp para descobrir quais servidores exigem login. O aviso conta apenas os servidores nos quais você pode fazer login a partir do Claude Code. Antes da v2.1.218, ele também contava conectores do claude.ai que não estavam conectados no claude.ai, os quais você só pode conectar pelas configurações do claude.ai.

O aviso anuncia cada servidor uma vez e o deixa fora da contagem nas inicializações seguintes até que esse servidor tenha se conectado e precise de login novamente. O /mcp continua listando todos os servidores que precisam de login.

Uma execução de claude -p ou do Agent SDK não tem o painel /mcp, então o Claude Code não pode executar o fluxo OAuth ali. Para usar um servidor que precisa de autenticação, conclua primeiro o login a partir de uma sessão interativa: execute /mcp na sessão, ou claude mcp login <name> no seu shell. Quando um servidor configurado precisa de autenticação durante uma execução de claude -p ou do Agent SDK com a busca de ferramentas habilitada, o Claude Code informa ao Claude que as ferramentas do servidor estão indisponíveis até que você o autorize.

Se você configurou headers.Authorization para o servidor e o servidor rejeita esse cabeçalho, o Claude Code informa que a conexão falhou em vez de recorrer ao OAuth. Verifique se o token é válido para o endpoint MCP, ou remova o cabeçalho para usar o fluxo OAuth.

1. Adicione o servidor que requer autenticação

Se você já adicionou o servidor sentry no início rápido de MCP, pule esta etapa: executar claude mcp add novamente com o mesmo nome de servidor no mesmo escopo falha com MCP server sentry already exists in local config. Caso contrário, execute:

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

2. Use o comando /mcp dentro do Claude Code

No Claude Code, use o comando:

/mcp

Em seguida, siga as etapas no seu navegador para fazer login.

[!TIP]

Dicas:

• Os tokens de autenticação são armazenados com segurança e atualizados automaticamente
• Use "Clear authentication" no menu /mcp para revogar o acesso
• Se o seu navegador não abrir automaticamente, copie a URL fornecida e abra-a manualmente
• Se o redirecionamento do navegador falhar com um erro de conexão após a autenticação, cole a URL de callback completa da barra de endereços do seu navegador no prompt de URL que aparece no Claude Code
• A autenticação OAuth funciona com servidores HTTP

Autenticar pela linha de comando

O comando claude mcp login <name> executa o fluxo OAuth de um servidor configurado diretamente do seu shell, para que você não precise abrir o painel /mcp dentro de uma sessão. Para um conector do claude.ai, siga Autorizar um conector novamente a partir do seu shell.

claude mcp login sentry

Para limpar as credenciais armazenadas posteriormente, execute claude mcp logout <name>.

O claude mcp login detecta quando nenhum navegador local está disponível, como durante uma sessão SSH ou no Linux sem um servidor de exibição, e imprime a URL de autorização em vez de tentar abrir um navegador. Abra a URL na sua máquina local e cole a URL de redirecionamento completa da barra de endereços do seu navegador de volta no prompt. O comando precisa de um terminal interativo para a etapa de colar, então conecte-se com ssh -t. Passe --no-browser para forçar o prompt de URL mesmo quando um navegador local for detectado.

claude mcp login sentry --no-browser

Usar uma porta de callback OAuth fixa

Alguns servidores MCP exigem um URI de redirecionamento específico registrado previamente. Por padrão, o Claude Code escolhe uma porta aleatória disponível para o callback OAuth. Use --callback-port para fixar a porta de modo que ela corresponda a um URI de redirecionamento pré-registrado no formato http://localhost:PORT/callback. Se o login no Claude Code v2.1.229 falhar com uma incompatibilidade de URI de redirecionamento, consulte a nota de versão em Usar credenciais OAuth pré-configuradas.

Você pode usar --callback-port sozinho (com registro dinâmico de cliente) ou junto com --client-id (com credenciais pré-configuradas).

# Fixed callback port with dynamic client registration
claude mcp add --transport http \
  --callback-port 8080 \
  my-server https://mcp.example.com/mcp

Usar credenciais OAuth pré-configuradas

Alguns servidores MCP não oferecem suporte à configuração automática de OAuth via Dynamic Client Registration. Se você vir um erro como "Incompatible auth server: does not support dynamic client registration", o servidor requer credenciais pré-configuradas. O Claude Code também oferece suporte a servidores que usam um Client ID Metadata Document (CIMD) em vez de Dynamic Client Registration, e os descobre automaticamente. Se a descoberta automática falhar, registre primeiro um app OAuth pelo portal de desenvolvedores do servidor e, em seguida, forneça as credenciais ao adicionar o servidor.

1. Registre um app OAuth com o servidor

Crie um app pelo portal de desenvolvedores do servidor e anote seu client ID e client secret.

Se o formulário de registro pedir um URI de redirecionamento, escolha qualquer porta disponível e insira http://localhost:PORT/callback com essa porta. Você usará a mesma porta na próxima etapa.

Na v2.1.229, o Claude Code enviava http://127.0.0.1:PORT/callback em vez disso, e servidores que exigem correspondência exata com o URI de redirecionamento registrado rejeitavam o login com uma incompatibilidade de URI de redirecionamento. O Claude Code v2.1.231 restaurou o formato localhost. Para se recuperar na v2.1.229, atualize o Claude Code ou adicione temporariamente o formato http://127.0.0.1:PORT/callback aos URIs de redirecionamento registrados do servidor.

2. Adicione o servidor com suas credenciais

As abas cobrem os dois comandos: claude mcp add recebe seu client ID e a porta de callback como flags, e claude mcp add-json os recebe em um objeto oauth. Se você registrou um URI de redirecionamento, defina a porta de callback como a porta desse URI.

[tab] claude mcp add

Use --client-id para passar o client ID do seu app. A flag --client-secret solicita o secret com entrada mascarada:

claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

[tab] claude mcp add-json

Inclua o objeto oauth na configuração JSON e passe --client-secret como uma flag separada:

claude mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \
  --client-secret

[tab] claude mcp add-json (somente porta de callback)

Para fixar apenas a porta de callback e deixar o Claude Code registrar o cliente automaticamente, defina callbackPort sozinho:

claude mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"callbackPort":8080}}'

[tab] CI / variável de ambiente

Defina o secret por meio de uma variável de ambiente para pular o prompt interativo:

MCP_CLIENT_SECRET=your-secret claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

3. Autentique no Claude Code

Execute /mcp no Claude Code e siga o fluxo de login no navegador.

[!TIP]

Dicas:

• O client secret é armazenado com segurança no keychain do seu sistema (macOS) ou em um arquivo de credenciais, não na sua configuração
• Você só pode definir o client secret ao adicionar o servidor. Quando você se autentica com claude mcp login ou a partir de /mcp, o Claude Code usa o secret armazenado e não solicita um nem lê MCP_CLIENT_SECRET
• Para adicionar ou alterar o secret posteriormente, remova o servidor com claude mcp remove <name> e adicione-o novamente com --client-secret e o mesmo --scope
• Se o servidor usa um cliente OAuth público sem secret, use apenas --client-id sem --client-secret
• Essas flags se aplicam apenas aos transportes HTTP e SSE. Elas não têm efeito em servidores stdio
• Use claude mcp get <name> para verificar se as credenciais OAuth estão configuradas para um servidor

Sobrescrever a descoberta de metadados OAuth

Aponte o Claude Code para uma URL específica de metadados do servidor de autorização OAuth para contornar a cadeia de descoberta padrão. Defina authServerMetadataUrl quando os endpoints padrão do servidor MCP apresentarem erro, ou quando você quiser rotear a descoberta por meio de um proxy interno. Por padrão, o Claude Code primeiro verifica os Protected Resource Metadata do RFC 9728 em /.well-known/oauth-protected-resource e, em seguida, recorre aos metadados do servidor de autorização do RFC 8414 em /.well-known/oauth-authorization-server.

Defina authServerMetadataUrl no objeto oauth da configuração do seu servidor em .mcp.json:

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration"
      }
    }
  }
}

A URL deve usar https://. O scopes_supported da URL de metadados sobrescreve os escopos que o servidor upstream anuncia.

Restringir escopos OAuth

Defina oauth.scopes para fixar os escopos que o Claude Code solicita durante o fluxo de autorização. Essa é 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ços, correspondendo ao formato do parâmetro scope no RFC 6749 §3.3.

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "scopes": "channels:read chat:write search:read"
      }
    }
  }
}

oauth.scopes tem precedência sobre authServerMetadataUrl e sobre os escopos que o servidor descobre em /.well-known. Deixe-o sem definir para permitir que o servidor MCP determine o conjunto de escopos solicitados.

Quando oauth.scopes não está definido, o Claude Code não solicita o catálogo completo de scopes_supported dos metadados do servidor de autorização descobertos automaticamente. Metadados obtidos de um authServerMetadataUrl configurado ainda fornecem seu scopes_supported como os escopos solicitados.

Se o servidor de autorização anunciar offline_access em scopes_supported, o 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 posteriormente retornar um 403 insufficient_scope para uma chamada de ferramenta, a chamada falha com uma mensagem needs additional permissions que nomeia o escopo que o servidor solicita. O servidor aparece como precisando de autenticação em /mcp.

Se esse escopo não estiver no seu oauth.scopes fixado, adicione-o e, em seguida, execute /mcp e autentique o servidor novamente. O Claude Code solicita os escopos fixados em vez do escopo que o servidor nomeou, então, se você se autenticar novamente sem adicioná-lo, o token que você obtém continuará sem ele.

Usar OAuth com um servidor atrás de um proxy com autenticação

Se o seu servidor MCP usa OAuth atrás de um proxy ou gateway que verifica um cabeçalho próprio, o login falha quando as requisições OAuth chegam sem esse cabeçalho. Fazer login através do proxy requer o Claude Code v2.1.299 ou posterior, com o cabeçalho e o login ambos configurados:

• O cabeçalho do proxy: passe-o com --header, o campo headers ou um headersHelper, com o nome que o proxy lê
• O login OAuth: mantenha Authorization fora dos cabeçalhos configurados e, em seguida, faça login com claude mcp login <name> no seu shell. Se você configurar um cabeçalho Authorization, o Claude Code o usa como a credencial do servidor e não recorre ao OAuth para esse servidor.

Usar cabeçalhos dinâmicos para autenticação personalizada

Quando uma autenticação como Kerberos, tokens de curta duração ou SSO interno precisa de cabeçalhos gerados no momento da conexão, defina o headersHelper do servidor como um comando. O Claude Code o executa ao se conectar e mescla sua saída nos cabeçalhos que envia. Este exemplo usa um script:

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "/opt/bin/get-mcp-auth-headers.sh"
    }
  }
}

O comando também pode ser inline:

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "echo '{\"Authorization\": \"Bearer '\"$(get-token)\"'\"}'"
    }
  }
}

Requisitos:

• O comando deve escrever em stdout um objeto JSON de pares chave-valor do tipo string
• O Claude Code executa o comando em um shell e desiste dele após 10 segundos
• O Claude Code escolhe o diretório de trabalho do comando de acordo com onde você configurou o servidor, então forneça o script como um caminho absoluto ou coloque-o no PATH
• Cabeçalhos dinâmicos sobrescrevem quaisquer headers estáticos com o mesmo nome

O Claude Code executa o helper novamente a cada conexão, no início da sessão e na reconexão, assim que a regra de confiança para servidores de escopo de projeto e local permitir sua execução. Ele não armazena o resultado em cache, então seu script é responsável por qualquer reutilização de token.

Se uma chamada de ferramenta retornar 401 Unauthorized ou 403 Forbidden, o Claude Code executa automaticamente o helper novamente sob a mesma regra, reconecta com os novos cabeçalhos e tenta novamente a chamada uma vez. O Claude Code marca o servidor como precisando de autenticação em /mcp somente se essa nova tentativa também falhar.

Quando a saída do helper inclui um cabeçalho Authorization, o Claude Code usa essa credencial como a autenticação do servidor e não recorre ao OAuth para o servidor.

Se o servidor rejeitar a credencial do helper durante a conexão, o Claude Code informa que a conexão falhou em vez de marcar o servidor como precisando de autenticação. Corrija a credencial que seu helper retorna e, em seguida, reconecte a partir de /mcp para executar o helper novamente.

O Claude Code define estas variáveis de ambiente ao executar o helper:

Use-as para escrever um único script helper que atenda a vários servidores MCP.

Um headersHelper fornecido por um plugin não pode referenciar os valores ${user_config.*} do plugin, porque o comando é executado por meio de um shell. O Claude Code informa que o servidor está configurado incorretamente com um erro e não substitui o valor. Em vez disso, coloque ${user_config.KEY} no campo headers do servidor, que não é interpretado pelo shell, ou faça com que o script helper leia o valor de um arquivo de configuração. Antes da v2.1.207, o headersHelper substituía os valores ${user_config.*}.

Onde o helper é executado

O Claude Code escolhe o diretório de trabalho do comando headersHelper a partir da configuração que declara o servidor. Um cd que o Claude executa no Bash não o altera, e /cd o altera apenas para servidores executados a partir do diretório de trabalho principal da sessão. Cada linha abaixo indica o diretório em relação ao qual um caminho relativo no seu comando headersHelper é resolvido.

Antes da v2.1.238, o Claude Code também executava os helpers de servidores de escopo de usuário, gerenciados e de conectores do claude.ai, e de arquivos de agente de fora do seu projeto, a partir do diretório em que você o iniciou.

Quais variáveis um helper pode ler

Um headersHelper fornecido por um repositório ou plugin é um comando que você não escreveu, então o Claude Code o executa sem as variáveis de credenciais do seu ambiente, como ANTHROPIC_API_KEY. Onde você configurou o servidor decide se isso se aplica:

• Removidas: um servidor em um .mcp.json de projeto ou em um plugin, e um servidor inline em um arquivo de agente do seu projeto ou de um diretório --add-dir
• Não removidas: um servidor no escopo de usuário ou escopo local, em MCP gerenciado, de um conector do claude.ai ou fornecido pelo SDK ou por --mcp-config, e um servidor inline em um arquivo de agente de ~/.claude/agents/, de configurações gerenciadas ou passado com --agents

Com exceção das variáveis GIT_CONFIG_KEY_<n> do Git, o Claude Code remove do seu ambiente todas as variáveis cujo nome pareça uma credencial, como um nome que contenha TOKEN, SECRET, PASSWORD, KEY ou AUTH em maiúsculas ou minúsculas, então ANTHROPIC_API_KEY e MY_REGISTRY_TOKEN são ambas removidas. O Claude Code também remove uma lista fixa de variáveis de credenciais cujos nomes não seguem esse padrão, como ANTHROPIC_CUSTOM_HEADERS.

Quando isso se aplicar ao seu helper, faça com que o script leia sua credencial de um arquivo ou de um repositório de credenciais. Se a url do servidor carregar o valor real de uma dessas variáveis, como MY_REGISTRY_TOKEN, o valor de CLAUDE_CODE_MCP_SERVER_URL que o helper recebe também terá essa parte substituída por REDACTED.

Confiar em uma pasta antes que seu headersHelper seja executado

O Claude Code executa um headersHelper como um comando de shell arbitrário. Para um servidor em um .mcp.json de projeto ou no escopo local, ele executa o helper somente depois que você aceita a caixa de diálogo de confiança para o diretório do projeto no qual o servidor está declarado. Antes da v2.1.238, uma sessão de claude -p ou do SDK executava esses helpers sem verificar a confiança, e uma sessão interativa os executava assim que você confiasse em uma pasta pai.

• Confiança que não conta: a confiança em uma pasta pai e a confiança automática que uma sessão de claude -p ou do SDK obtém para hooks em arquivos de configuração
• Até você confiar na pasta: o Claude Code conecta o servidor apenas com seus headers estáticos. Em uma sessão de claude -p ou do SDK, ele também imprime uma linha headersHelper not run por servidor em stderr, informando como conceder a confiança.
• Confiança sem caixa de diálogo: defina projects["<path>"].hasTrustDialogAccepted como true em ~/.claude.json. <path> é a pasta à qual, segundo Regras de permissão do projeto e confiança do workspace, o Claude Code associa a confiança.

O Claude Code aplica a mesma regra a um servidor declarado inline em um arquivo de agente, verificando de onde esse arquivo de agente veio: do seu projeto, para um arquivo no diretório .claude/agents/ dele, ou de um diretório --add-dir. Até que você confie nesse projeto ou diretório em si, o Claude Code não carrega o servidor de forma alguma, então seu helper também nunca é executado.

Fazer login em um servidor MCP atrás de um gateway que exige um cabeçalho

O login OAuth em um servidor MCP falha quando um gateway exige um cabeçalho, como X-API-Key, e o Claude Code não o envia. Para que o Claude Code envie esse cabeçalho, adicione-o à configuração do servidor e use o Claude Code v2.1.299 ou posterior:

• Um servidor cuja configuração você pode editar: defina-o em headers ou retorne-o a partir de um headersHelper
• Um servidor fornecido por MCP gerenciado ou por um plugin: peça ao seu administrador ou ao autor do plugin para adicionar o cabeçalho à entrada do servidor

O Claude Code então adiciona os cabeçalhos configurados, exceto Authorization, às requisições de login, atualização de token e revogação de token que envia para a origem do servidor. A origem do servidor é o esquema, o host e a porta em sua url. Um gateway que exige o cabeçalho ainda pode interromper o login na página de autorização ou em um servidor de autorização em outra origem:

• A página de autorização: você faz login nesta página no seu navegador, que não envia os cabeçalhos configurados. Se o seu navegador receber o erro do gateway em vez da página, peça a quem administra o gateway para deixar a página passar sem o cabeçalho.
• Um servidor de autorização em outra origem: se um gateway na frente desse servidor também exigir o cabeçalho, o login falha ali. Peça a quem administra esse gateway para deixar as requisições OAuth passarem sem o cabeçalho.

Adicionar servidores MCP de configuração JSON

Se você tiver uma configuração JSON para um servidor MCP, você pode adicioná-la diretamente:

1. Adicione um servidor MCP de JSON

# Sintaxe básica
claude mcp add-json <name> '<json>'

# Exemplo: Adicionar um servidor HTTP com configuração JSON
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

# Exemplo: Adicionar um servidor stdio com configuração JSON
claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

# Exemplo: Adicionar um servidor HTTP com credenciais OAuth pré-configuradas
claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --client-secret

2. Verifique se o servidor foi adicionado

claude mcp get weather-api

[!TIP]

Dicas:

• Certifique-se de que o JSON está adequadamente escapado no seu shell
• O JSON deve estar em conformidade com o esquema de configuração do servidor MCP
• Você pode usar --scope user para adicionar o servidor à sua configuração de usuário em vez da específica do projeto

Importar servidores MCP do Claude Desktop

Se você já configurou servidores MCP no Claude Desktop, você pode importá-los:

1. Importe servidores do Claude Desktop

# Sintaxe básica 
claude mcp add-from-claude-desktop 

2. Selecione quais servidores importar

Após executar o comando, você verá um diálogo interativo que permite selecionar quais servidores você deseja importar.

3. Verifique se os servidores foram importados

claude mcp list 

Os nomes de servidores adicionados através de comandos claude mcp podem conter apenas letras, números, hífens e sublinhados. O Claude Desktop não aplica essa restrição, portanto um servidor do Claude Desktop cujo nome contém qualquer outro caractere, como um espaço, não pode ser importado. A importação relata cada nome que rejeita e ainda importa os outros servidores que você selecionou.

[!TIP]

Dicas:

• Este recurso funciona apenas em macOS e Windows Subsystem for Linux (WSL)
• Ele lê o arquivo de configuração do Claude Desktop de sua localização padrão nessas plataformas
• Use a flag --scope user para adicionar servidores à sua configuração de usuário
• Os servidores importados mantêm os mesmos nomes que no Claude Desktop quando o nome contém apenas letras, números, hífens e sublinhados. O Claude Code relata um servidor cujo nome contém qualquer outro caractere e o ignora
• Se servidores com os mesmos nomes já existirem, eles receberão um sufixo numérico (por exemplo, server_1)

Usar servidores MCP do claude.ai

Se você fez login no Claude Code com uma conta do claude.ai, os servidores MCP que você adicionou no claude.ai, conhecidos como conectores, ficam automaticamente disponíveis no Claude Code:

1. Configurar servidores MCP no claude.ai

Adicione servidores em claude.ai/customize/connectors. Nos planos Team e Enterprise, apenas administradores podem adicionar servidores.

2. Autenticar o servidor MCP

Conclua todas as etapas de autenticação necessárias no claude.ai.

3. Visualizar e gerenciar servidores no Claude Code

No Claude Code, use o comando:

/mcp

Os servidores do claude.ai aparecem na lista com indicadores mostrando que vêm do claude.ai.

A Anthropic também fornece alguns conectores por conta própria, sem que você ou um administrador precise adicioná-los. Em contas nas quais o Claude Docs está disponível, /mcp lista claude.ai Claude Docs sem nenhuma configuração, e o Claude o usa quando você pede um documento destinado a outras pessoas. Para desativar apenas este conector, consulte Desativar conectores do claude.ai.

O Claude Code marca um conector como managed no /mcp e no gerenciador do /plugin quando sua organização gerencia a autenticação dele no claude.ai. O status de gerenciado não altera a forma como o Claude Code se conecta ao conector nem como aplica os controles de ferramentas da sua organização.

Os conectores nos quais você nunca fez login ficam recolhidos atrás de uma linha Show unused connectors no final da seção do claude.ai, para que uma lista provisionada pela organização não preencha o painel. Selecione a linha para expandi-los. Um conector no qual você já fez login antes permanece visível mesmo quando precisa de uma nova autenticação no momento.

Os conectores do claude.ai são buscados apenas quando seu método de autenticação ativo é um login de assinatura do claude.ai. Eles não são carregados, mesmo que você tenha executado /login anteriormente, quando:

• ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN ou apiKeyHelper está ativo
• Um provedor terceirizado, como Amazon Bedrock ou o Agent Platform do Google Cloud, está ativo
• ANTHROPIC_PROFILE, as variáveis de federação ou um perfil da Anthropic ativo fornece a credencial
• CLAUDE_CODE_OAUTH_TOKEN contém um token de claude setup-token, que só pode fazer requisições ao modelo

Se o /mcp não listar um conector que você adicionou, execute /status para confirmar qual método de autenticação está ativo. Remova a definição dessa variável de ambiente, remova a configuração apiKeyHelper ou desative o perfil e, em seguida, execute /login para selecionar sua conta do claude.ai.

Se um problema temporário de rede impedir que a lista de conectores seja carregada quando sua sessão começa, o Claude Code tenta buscá-la novamente até três vezes em segundo plano, e os conectores aparecem assim que uma nova tentativa for bem-sucedida. Se ainda assim eles não aparecerem, reinicie o Claude Code para buscar a lista novamente.

Se o /mcp mostrar um conector como session token rejected, ou se a visualização de detalhes dele mostrar claude.ai rejected the session token, o claude.ai rejeitou o token do seu login do Claude Code. Autorizar o conector novamente não limpa esse estado, porque não foi a autorização do próprio conector no claude.ai que foi rejeitada. Para limpá-lo:

1. Execute /login para fazer login novamente.
2. Reconecte o conector a partir do /mcp.

Antes da v2.1.222, o Claude Code marcava os conectores como precisando de autenticação, e autorizá-los não resolvia o problema.

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, o /mcp lista o conector como oculto e mostra como remover a duplicata, caso você prefira usar o conector.

Alguns conectores hospedados pela Anthropic, como Microsoft 365, Gmail e Google Calendar, não oferecem suporte a OAuth local a partir do Claude Code, porque o provedor de identidade upstream aceita apenas a URL de redirecionamento que o claude.ai registrou. Quando um servidor que você adicionou com claude mcp add ou em .mcp.json aponta para um desses hosts e você faz login nele a partir do /mcp ou com claude mcp login, o Claude Code mostra is Anthropic-hosted and doesn't support local OAuth, orientando você a conectar o serviço em claude.ai/customize/connectors.

Depois que você remove sua entrada com claude mcp remove <name> e conecta o serviço no claude.ai, o conector aparece automaticamente no Claude Code.

Como os conectores chegam ao Claude Code

Quais configurações regem um conector do claude.ai depende de onde sua sessão é executada, porque apenas algumas sessões buscam conectores do claude.ai por conta própria. Cada linha abaixo indica como os conectores chegam a um tipo de sessão e o que os controla nesse caso. As sessões WSL do aplicativo desktop não têm uma linha porque os conectores ainda estão sendo disponibilizados para elas.

disableClaudeAiConnectors, ENABLE_CLAUDEAI_MCP_SERVERS e allowAllClaudeAiMcps atuam apenas na primeira linha, os conectores que o próprio Claude Code busca. As outras duas linhas diferem dela das seguintes formas:

• Sessões na nuvem: entradas allowedMcpServers e deniedMcpServers que chegam à sessão, por exemplo por meio de configurações gerenciadas pelo servidor, também filtram os conectores entregues. O proxy da sessão reescreve a URL de cada conector, portanto um padrão serverUrl escrito para a URL própria do conector não corresponde a ele. Para admitir conectores entregues junto com uma allowlist de URLs em um ambiente auto-hospedado, adicione as entradas serverUrl listadas em O tráfego dos conectores sai da sua rede. O Claude Code descarta os conectores entregues quando há um managed-mcp.json no host que executa a sessão, como um host de runner auto-hospedado, independentemente de você definir allowAllClaudeAiMcps ou não.
• Sessões locais e SSH do aplicativo desktop: o aplicativo desktop registra os conectores como servidores type: "sdk" no mesmo processo, e nenhuma configuração de MCP ou managed-mcp.json os alcança. Um usuário mantém um conector fora das próprias sessões desconectando-o em claude.ai/customize/connectors. Uma organização bloqueia as ferramentas de um conector ou desativa completamente o Claude Code no aplicativo desktop.

Controles da organização sobre ferramentas de conectores

Sua organização pode definir controles por ferramenta nos conectores do claude.ai. O Claude Code lê essas configurações na inicialização e as aplica localmente, exceto nas sessões locais e SSH do aplicativo desktop. Nelas, o aplicativo desktop retém as ferramentas blocked antes de entregar um conector, e a configuração ask não chega ao Claude Code, que então aplica as regras de permissão comuns da sessão a essas ferramentas em vez de pedir confirmação a cada chamada. Nas sessões em que o próprio Claude Code busca os conectores, execute /mcp para ver qual configuração se aplica a cada ferramenta de um conector.

• Ferramenta definida como ask: o Claude Code pede confirmação a cada chamada com o motivo Your organization requires approval for this tool. O prompt aparece mesmo nos modos de permissão acceptEdits, auto e bypassPermissions. No terminal, o prompt não tem opção para lembrar sua escolha. Regras de permissão allow que correspondem à ferramenta também não ignoram o prompt. No modo dontAsk, que nunca pede confirmação, o Claude Code nega a chamada.
• Ferramenta definida como blocked: o Claude Code filtra a ferramenta antes que o Claude a veja, então ela nunca aparece na lista de ferramentas do Claude. Nas sessões em que o próprio Claude Code busca os conectores, a lista de ferramentas do /mcp ainda mostra a ferramenta, marcada como disabled by your organization.

O aplicativo desktop e o chat do claude.ai aplicam a mesma configuração blocked, então o Claude também não pode usar uma ferramenta bloqueada neles, e você não pode reter uma ferramenta das sessões do aplicativo desktop enquanto a mantém disponível no chat. O aplicativo desktop ignora um conector cujas ferramentas estão todas bloqueadas.

Desativar conectores do claude.ai

O Claude Code aplica disableClaudeAiConnectors apenas aos conectores que ele busca por conta própria, não aos conectores que um host na nuvem ou o aplicativo desktop entrega. Para desativar os conectores que ele busca, defina a configuração como true em qualquer escopo de configurações:

{
  "disableClaudeAiConnectors": true
}

Essa configuração usa a semântica de qualquer origem verdadeira: true em qualquer origem de configurações tem precedência. Um .claude/settings.json de projeto versionado no repositório pode excluir um repositório dos conectores que o próprio Claude Code busca, mas um false no nível do projeto não pode reativar conectores que um true no nível do usuário ou da política desativou. Servidores passados explicitamente via --mcp-config não são afetados.

Você também pode definir a variável de ambiente ENABLE_CLAUDEAI_MCP_SERVERS como false, o que tem o mesmo efeito para a sessão atual do shell:

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

Para bloquear conectores individuais do claude.ai em vez de todos eles, adicione-os a deniedMcpServers por nome ou por padrão de URL. Por exemplo, uma entrada serverName de "claude.ai Slack" bloqueia o conector do Slack. Você também pode executar /mcp para ativar ou desativar qualquer conector que o Claude Code busca apenas para o projeto atual.

Use Claude Code as an MCP server

Você pode usar Claude Code como um servidor MCP que outros aplicativos podem conectar:

# Start Claude as a stdio MCP server
claude mcp serve

O comando não imprime nada quando inicia. Um servidor MCP stdio se comunica através de stdin e stdout, então um terminal silencioso e bloqueado significa que o servidor está em execução e aguardando um cliente para se conectar.

Você pode usar isso no Claude Desktop adicionando esta configuração ao claude_desktop_config.json:

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

[!WARNING]

Configurando o caminho do executável: o campo command deve fazer referência ao executável Claude Code. Se o comando claude não estiver no PATH do seu sistema, você precisará especificar o caminho completo para o executável.

Para encontrar o caminho completo:

which claude

Em seguida, use o caminho completo em sua configuração:

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "/full/path/to/claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

Sem o caminho correto do executável, você encontrará erros como spawn claude ENOENT.

[!TIP]

Dicas:

• No Claude Desktop, tente pedir ao Claude para ler arquivos em um diretório, fazer edições e muito mais.
• Este servidor MCP apenas expõe as ferramentas do Claude Code ao seu cliente MCP, portanto seu próprio cliente é responsável por implementar confirmação do usuário para chamadas de ferramentas individuais.

Ler a saída de um comando em segundo plano como cliente MCP

Um campo backgroundOutputPath em um resultado de Bash ou PowerShell de claude mcp serve significa que a chamada deixou seu comando em execução em segundo plano. Um comando é executado em segundo plano quando seu cliente define run_in_background: true na chamada. Um comando em primeiro plano também pode passar para o segundo plano quando atinge seu timeout.

O campo está no texto JSON do resultado e contém o caminho do arquivo de saída do comando.

• Para ler a saída até o momento: abra o arquivo nesse caminho a partir do seu cliente, ou passe o caminho como file_path para a ferramenta Read do servidor
• Para saber quando o comando terminou: acrescente um echo de uma string fixa ao valor de command, como em npm test; echo DONE. O comando terminou quando essa string aparece no arquivo. Sem a string, nada marca o fim, porque Claude Code não adiciona nenhuma linha de encerramento ao arquivo e não notifica seu cliente.
• Para ler o final de uma saída longa: Read com apenas file_path retorna a primeira página, ou falha quando o arquivo excede o limite de tamanho. Passe também offset e limit, o que funciona com qualquer tamanho de arquivo:
  1. Chame Read com offset e limit ambos definidos como 1, e obtenha totalLines do resultado
  2. Chame Read novamente com offset definido como totalLines menos nove e limit definido como 10
  3. Procure sua string de echo nas últimas dez linhas, que a segunda chamada retorna

O campo backgroundOutputPath requer Claude Code v2.1.295 ou posterior.

Limites de saída do MCP e avisos

Quando as ferramentas do MCP produzem grandes saídas, Claude Code ajuda a gerenciar o uso de tokens para evitar sobrecarregar o contexto da sua conversa:

• Limite de aviso de saída: Claude Code exibe um aviso quando qualquer saída de ferramenta do MCP excede 10.000 tokens
• Limite configurável: você pode ajustar o máximo de tokens de saída do 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/maxResultSizeChars usam esse valor em vez disso para conteúdo de texto, independentemente do que MAX_MCP_OUTPUT_TOKENS está definido. Ferramentas que retornam dados de imagem ainda estão sujeitas a MAX_MCP_OUTPUT_TOKENS
• Acima do limite: quando um resultado bem-sucedido sem conteúdo de imagem excede o limite de tokens, Claude Code o salva em um arquivo e o substitui na conversa com uma mensagem que nomeia o caminho do arquivo, para que Claude leia o arquivo quando precisar do conteúdo. O arquivo fica no diretório tool-results da sessão em ~/.claude/projects/.
• Tamanho da resposta de servidores HTTP e SSE: quando uma resposta de um servidor HTTP ou SSE ultrapassa 16 MiB, Claude Code para de lê-la e a requisição falha. O limite se aplica após a descompressão a um corpo de resposta JSON ou a um evento de um fluxo de eventos. Se você mantém o servidor, retorne menos dados por resposta para permanecer abaixo do limite, por exemplo, paginando os resultados
• Tamanho da mensagem de servidores WebSocket: quando um servidor WebSocket envia uma mensagem com mais de 16 MiB, Claude Code fecha a conexão, e as chamadas em andamento nesse servidor falham. Se você mantém o servidor, retorne menos dados por mensagem para permanecer abaixo do limite

Uma chamada que Claude Code moveu para uma tarefa em segundo plano informa seu resultado por meio da notificação da tarefa. Mais dois limites se aplicam a uma chamada que é concluída em primeiro plano:

• Limite de caracteres para resultados de texto: para uma ferramenta que não declara anthropic/maxResultSizeChars, Claude Code salva em um arquivo um resultado bem-sucedido sem conteúdo de imagem quando ele ultrapassa 50.000 caracteres, qualquer que seja sua contagem de tokens. Definir MAX_MCP_OUTPUT_TOKENS não altera esse limite
• Resultados de erro: quando uma ferramenta retorna um resultado marcado como isError: true, Claude recebe o texto do resultado como a mensagem de erro da ferramenta. Texto de erro com mais de cerca de 11.000 caracteres mantém apenas seus primeiros 5.000 e últimos 5.000 caracteres, com um marcador entre eles que informa quantos caracteres foram removidos

Para alterar o limite de tokens, defina MAX_MCP_OUTPUT_TOKENS no seu shell antes de iniciar o Claude Code:

export MAX_MCP_OUTPUT_TOKENS=50000
claude

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 de 50.000 caracteres, definindo _meta["anthropic/maxResultSizeChars"] na entrada de resposta tools/list da ferramenta. Claude Code aumenta o limite dessa ferramenta para o valor anotado, até um limite máximo 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 bem-sucedidos que excedem o limite padrão são persistidos em disco e substituídos por uma referência de arquivo na conversa.

{
  "name": "get_schema",
  "description": "Returns the full database schema",
  "_meta": {
    "anthropic/maxResultSizeChars": 200000
  }
}

A anotação se aplica independentemente de MAX_MCP_OUTPUT_TOKENS para conteúdo de texto, portanto 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 tokens.

Imagens em resultados de ferramentas

Quando uma ferramenta do MCP retorna uma imagem PNG, JPEG, GIF ou WebP, Claude vê a imagem inline na conversa. A cópia inline pode ser redimensionada ou comprimida para se adequar aos limites de tamanho de imagem do modelo. Claude Code também salva os bytes originais em um arquivo no diretório tool-results da sessão em ~/.claude/projects/ e fornece o caminho a Claude. Claude pode então cortar, converter ou reutilizar o arquivo em resolução completa com ferramentas como Bash.

Se você desabilitar a persistência de sessão com --no-session-persistence ou CLAUDE_CODE_SKIP_PROMPT_HISTORY, Claude Code não escreve nenhum arquivo de imagem e Claude recebe apenas a cópia inline.

Salvar resultados de imagem do MCP em um arquivo requer Claude Code v2.1.283 ou posterior.

Esquemas de entrada de ferramentas com um combinador no nível raiz

Alguns servidores MCP declaram o esquema de entrada de uma ferramenta como uma união JSON Schema, com anyOf, oneOf ou allOf no nível superior do esquema. A API Claude não aceita essas palavras-chave na raiz do esquema. Ela aceita combinadores aninhados dentro de properties, que Claude Code envia sem alterações.

Ferramentas com um combinador no nível raiz permanecem disponíveis. Antes de enviar a ferramenta para a API, Claude Code achata o esquema em um único objeto e prepara uma frase para a descrição da ferramenta que diz ao Claude quais grupos de parâmetros pertencem juntos:

• allOf: as propriedades de cada branch são mescladas, e a lista required de cada branch ainda se aplica
• anyOf e oneOf: as propriedades de cada branch são mescladas, e a lista required de cada branch é descrita na descrição da ferramenta em vez de ser imposta pelo esquema

Seu servidor recebe quaisquer argumentos que Claude escolheu, portanto continue validando a combinação no lado do servidor.

Quando Claude Code não consegue produzir um esquema que a API aceita, ou em uma implantação que não recebe a configuração remota que habilita a reescrita, ele pula essa ferramenta, registra o motivo no log do servidor e deixa as outras ferramentas do servidor disponíveis.

Ferramentas com esquemas de entrada inválidos

[!NOTE]

Se sua sessão falhar com um erro 400 que nomeia uma ferramenta por sua posição, siga as etapas em Tool input schema is invalid.

Se uma das ferramentas do seu servidor MCP tiver um esquema de entrada que viole qualquer uma das duas regras que a API impõe, Claude Code exclui essa ferramenta. As outras ferramentas do servidor não são afetadas. Claude Code verifica ambas as regras ao carregar as ferramentas do servidor:

• Os nomes de propriedades de nível superior devem ter de 1 a 64 caracteres e usar apenas letras ASCII e dígitos, _, . e -
• O esquema deve ser válido em relação ao meta-esquema JSON Schema draft 2020-12. Claude Code aplica essa verificação a esquemas que não declaram $schema e esquemas que declaram draft 2020-12. Um esquema que declara qualquer outro dialeto ignora essa verificação, embora a verificação de nome de propriedade acima ainda se aplique

Quando Claude Code exclui uma ferramenta, registra o motivo no log do servidor e informa ao Claude quais ferramentas foram excluídas e por quê, para que você possa perguntar ao Claude por que uma ferramenta está faltando. Se você corrigir o esquema no servidor, a ferramenta reaparece na próxima vez que Claude Code carregar as ferramentas do servidor.

Quando a busca de feature flags está desativada ou as flags nunca chegaram, como em uma máquina isolada, uma ferramenta que viola uma regra não é excluída:

• Claude recebe a ferramenta sem alterações, e o log do servidor registra input schema would be rejected by the Anthropic API para ela
• Se a API então rejeitar o esquema, consulte Ferramentas cujo esquema de entrada a API recusa

Antes da v2.1.216, nenhuma implantação executava essas verificações.

O tratamento do combinador de nível raiz é separado e mantém seu próprio comportamento quando a busca de sinalizadores está desativada ou os sinalizadores nunca chegaram.

Ferramentas cujo esquema de entrada a API recusa

Se uma linha no log de depuração contiver the API refused this tool's input schema, ela nomeia uma ferramenta cujo esquema a API rejeitou em uma requisição. Claude Code reenvia essa requisição com a ferramenta declarada sem parâmetros.

• Se sua sessão falhar com um erro 400 que nomeia uma ferramenta por sua posição: siga as etapas em Tool input schema is invalid
• Se você usa o servidor: você não precisa fazer nada. Claude ainda pode chamar a ferramenta, mas não vê seus parâmetros
• Se você mantém o servidor: corrija o esquema de entrada da ferramenta no servidor. A linha do log termina com The API said: e o motivo da API para rejeitar o esquema. Valide os argumentos que o servidor recebe, porque Claude chama a ferramenta sem ver seus parâmetros

Antes da v2.1.300, todo turno que incluía o esquema recusado falhava com um erro 400 nomeando a ferramenta por sua posição.

Ferramentas com nomes maiores que 128 caracteres

Se /mcp listar uma ferramenta que Claude não consegue chamar, verifique se o nome completo da ferramenta tem mais de 128 caracteres. Execute /mcp na sua sessão e selecione a ferramenta para ver seu nome completo, como mcp__<server>__<tool>. O Claude Code deixa uma ferramenta MCP de fora das ferramentas que envia ao Claude quando seu nome completo tem mais de 128 caracteres. A API do Claude rejeita uma requisição que inclua tal ferramenta, portanto deixar a ferramenta de fora mantém as outras ferramentas do servidor funcionando.

Para a mensagem que nomeia a ferramenta e as formas de encurtar seu nome completo, consulte Nome de ferramenta MCP com mais de 128 caracteres.

Exigir aprovação para uma ferramenta específica

Se você está construindo um servidor MCP, pode marcar uma ferramenta como exigindo aprovação explícita em cada chamada definindo _meta["anthropic/requiresUserInteraction"] como true na entrada de resposta tools/list da ferramenta. O valor deve ser o booleano JSON true; qualquer outro valor é ignorado.

Claude Code mostra o prompt de permissão dessa ferramenta em cada chamada, mesmo em modos de permissão acceptEdits, auto e bypassPermissions, e não oferece uma opção "não perguntar novamente" para ela. Regras de allow que correspondem à ferramenta também não pulam o prompt. No modo dontAsk, que nunca solicita, Claude Code nega a chamada.

O prompt tem que chegar a uma pessoa. No modo não interativo com --permission-prompt-tool, um resultado allow da ferramenta de prompt para uma ferramenta marcada é convertido em uma negação com a mensagem MCP tool requires user interaction; not supported via --permission-prompt-tool. O callback canUseTool do Agent SDK recebe essas chamadas e pode aprová-las, porque sua aplicação SDK é esperada que as mostre a um usuário.

Use isso para ferramentas cujo prompt de permissão é em si o ponto, como uma etapa de consentimento ou concessão de acesso onde a aprovação automática significaria que nenhum humano nunca concordou. Outras ferramentas do mesmo servidor mantêm seu comportamento de permissão normal.

A seguinte entrada tools/list marca uma ferramenta como sempre exigindo aprovação.

{
  "name": "grant_access",
  "description": "Requests access to a protected resource",
  "_meta": {
    "anthropic/requiresUserInteraction": true
  }
}

Algumas superfícies, como Remote Control e aplicações construídas no Agent SDK, normalmente permitem que você aprove chamadas de ferramenta com um toque. Para uma ferramenta marcada com essa anotação, Claude Code retém a ação de um toque e mostra o prompt de permissão completo da ferramenta, então a aprovação ainda vem de uma pessoa respondendo ao prompt em vez de um toque.

Claude Code retém a aprovação de um toque da mesma forma para qualquer solicitação de permissão que apenas o diálogo do terminal possa renderizar completamente, como uma que carrega um aviso de segurança ou uma opção de sempre permitir que a superfície remota não possa mostrar. Você responde essa solicitação no diálogo do terminal em vez de pelo Remote Control.

Marque as ferramentas que podem ser chamadas duas vezes com segurança

Se você desenvolver um servidor MCP, marque as ferramentas que podem ser chamadas duas vezes com segurança para que o Claude Code possa repetir uma chamada que estava pendente quando uma conexão foi encerrada. O Claude Code pode repetir essa chamada para um servidor HTTP ou um conector do claude.ai uma vez, em uma nova conexão. Uma chamada que o Claude Code não repete pode falhar com connection closed before the tool call was answered.

Para marcar uma ferramenta, defina uma destas annotations como true em sua entrada de tools/list:

• idempotentHint: a ferramenta pode alterar algo, e chamá-la novamente com os mesmos argumentos é seguro
• readOnlyHint: a ferramenta não altera nada. O Claude Code também executa as chamadas da ferramenta em paralelo com outras chamadas somente leitura.

Por exemplo, estes campos em uma entrada de tools/list marcam a ferramenta set_issue_status como segura para repetir:

{
  "name": "set_issue_status",
  "annotations": {
    "idempotentHint": true
  }
}

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 no terminal 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 pergunta se você deseja abrir um link no seu navegador. Os servidores usam este modo para um fluxo que é concluído fora do terminal, como entrada.

No modo de URL, Claude Code passa a URL como um argumento de linha de comando para o manipulador de URL do seu sistema e limita o tamanho desse argumento. Quando a URL, uma vez escapada para a linha de comando, ultrapassa esse limite, você só pode recusar a solicitação. Cada caractere que precisa ser escapado, como % ou &, conta quatro vezes em relação ao limite: seu próprio caractere mais três caracteres de escape. Uma URL sem nenhum deles atinge o limite em aproximadamente 8.000 caracteres. Uma URL construída principalmente com percent-escapes, onde cada terceiro caractere é um %, atinge em aproximadamente 4.000.

Para responder automaticamente a solicitações de elicitação sem mostrar um diálogo, use o hook Elicitation.

Se você está construindo um servidor MCP que usa elicitação, consulte a especificação de elicitação MCP para detalhes do protocolo e exemplos de esquema.

Responder a uma solicitação de elicitação em uma sessão na nuvem

Quando a tarefa do Claude na sua sessão na nuvem aguarda uma solicitação de um servidor MCP, o servidor precisa de algo de você, como um valor ou um login. Se a solicitação aparecer como um cartão em claude.ai/code ou na guia Code do aplicativo Desktop, responda no cartão:

• Modo de formulário: preencha os campos e clique em Submit
• Modo de URL: clique em Open link, conclua o fluxo que ele abre e depois clique em I’m done, continue no cartão

Para recusar a solicitação, clique em Decline. Claude continua assim que o servidor responde.

Se você não vir nenhum cartão em nenhum desses lugares, não poderá responder à solicitação ali. Na sua própria sessão, clique no botão de parar ali para encerrar o turno.

Modos de elicitação que Claude Code declara

Se você desenvolve um servidor MCP, as capacidades de cliente que Claude Code envia ao se conectar informam ao seu servidor quais modos de elicitação ele pode solicitar. Claude Code declara elicitation: {form: {}, url: {}} nas seguintes conexões, portanto um servidor em qualquer uma delas pode solicitar ambos os modos:

• Conexões que usam revisão de protocolo 2026-07-28
• Conexões nas revisões de protocolo anteriores, 2025-11-25 e mais antigas, aos servidores stdio, sse, http e ws na configuração MCP do Claude Code de um usuário. Requer Claude Code v2.1.287 ou posterior

Em suas outras conexões nas revisões anteriores, como aos conectores do claude.ai, Claude Code declara apenas elicitation: {}, o que permite solicitações de elicitação somente no modo de formulário.

Um servidor criado com o Java MCP SDK 0.17.0 ou anterior pode recusar uma declaração que contenha form e url. Consulte MCP server rejected the elicitation capability.

Usar recursos MCP

Os servidores MCP podem expor recursos que você pode referenciar usando menções @, de forma semelhante a como você referencia arquivos.

Referenciar recursos MCP

1. Listar 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.

2. Referenciar um recurso específico

Use o formato @server:protocol://resource/path para referenciar um recurso:

Can you analyze @github:issue://123 and suggest a fix?

Please review the API documentation at @docs:file://api/authentication

3. Múltiplas referências de recursos

Você pode referenciar múltiplos recursos em um único prompt:

Compare @postgres:schema://users with @docs:file://database/user-model

[!TIP]

Dicas:

• Os recursos são automaticamente buscados e incluídos como anexos quando referenciados
• Os caminhos dos recursos são pesquisáveis por correspondência aproximada no preenchimento automático de menção @
• Claude Code fornece automaticamente ferramentas para listar e ler recursos MCP quando os servidores as suportam
• Os recursos podem conter qualquer tipo de conteúdo que o servidor MCP fornece (texto, JSON, dados estruturados, etc.)

Os recursos da UI do MCP Apps são entradas com um URI ui:// ou o tipo de mídia text/html;profile=mcp-app: páginas para um aplicativo host renderizar em vez de conteúdo para Claude ler. Eles não aparecem nas sugestões @ ou nos resultados da ferramenta de lista de recursos, e um servidor que oferece apenas recursos de UI mostra uma lista de recursos vazia. Ler um recurso de UI pelo seu URI ainda funciona.

Escalar com busca de ferramentas MCP

A busca de ferramentas mantém o uso de contexto MCP baixo ao adiar as definições de ferramentas até que Claude as necessite. Apenas nomes de ferramentas e instruções do servidor são carregados no início da sessão, portanto adicionar mais servidores MCP tem impacto mínimo na sua janela de contexto. Claude Code não impõe um limite fixo de ferramentas por servidor; o limite prático é o seu orçamento de janela de contexto.

[!NOTE]

A busca de ferramentas não é suportada em implantações do Microsoft Foundry hospedadas no Azure, que a rejeitam no lado do servidor: Claude Code detecta a rejeição e carrega as ferramentas MCP antecipadamente para essa implantação. ENABLE_TOOL_SEARCH não pode sobrescrever isso, pois a rejeição vem da implantação em si.

Busca de ferramentas para autores de servidores MCP

Se você está construindo um servidor MCP, o campo de instruções do servidor se torna mais útil com a busca de ferramentas ativada. As instruções do servidor ajudam Claude a entender quando procurar por suas ferramentas, de forma 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 procurar por suas ferramentas
• Capacidades principais que seu servidor fornece

Claude Code corta uma descrição de ferramenta ou instruções de servidor que ultrapassem estes limites padrão, e Claude vê apenas o texto antes do corte:

• Instruções do servidor e a descrição de uma ferramenta carregada antecipadamente: 4.096 caracteres
• A descrição de uma ferramenta que Claude carrega através da busca de ferramentas: 16.384 caracteres

Mantenha descrições e instruções concisas e coloque detalhes críticos perto do início. Quando a busca de ferramentas compara a consulta de Claude com a descrição de uma ferramenta, ela lê apenas a parte dentro do limite menor, então coloque também perto do início as palavras que Claude buscaria. Uma ferramenta é carregada antecipadamente e mantém o limite menor sempre que não é adiada, por exemplo quando a busca de ferramentas está desativada, quando a ferramenta está marcada para carregar antecipadamente ou quando seu servidor está isento do adiamento.

Antes da v2.1.296, o limite menor era de 2.048 caracteres e, antes da v2.1.295, ele se aplicava a todas as descrições de ferramentas, incluindo as carregadas através da busca de ferramentas.

Alterar os limites de tamanho das descrições

Para alterar os limites padrão de 4.096 e 16.384 caracteres para os servidores MCP em sua sessão, defina CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH como um número de caracteres. Claude Code usa esse número para ambos os limites. Com 8192, por exemplo, você aumenta o limite de 4.096 caracteres para instruções do servidor e descrições de ferramentas carregadas antecipadamente, e reduz o limite de 16.384 caracteres para descrições de ferramentas carregadas através da busca de ferramentas. Esta variável requer Claude Code v2.1.280 ou posterior.

Descrições e instruções de alguns dos servidores MCP que a Anthropic hospeda em api.anthropic.com chegam a Claude por completo, e definir esta variável não as corta.

Marcar uma ferramenta para carregar antecipadamente ou permanecer adiada

Para controlar como uma das ferramentas do seu servidor é carregada, defina "anthropic/alwaysLoad" no objeto _meta dessa ferramenta. A pessoa que adiciona seu servidor ao Claude Code também pode definir alwaysLoad para o servidor inteiro na configuração dela, e essa opção de configuração pode sobrescrever a sua:

A seguinte entrada de tools/list solicita que uma ferramenta seja carregada antecipadamente:

{
  "name": "search_tickets",
  "description": "Searches the ticket tracker by keyword",
  "_meta": {
    "anthropic/alwaysLoad": true
  }
}

Configurar busca de ferramentas

A busca de ferramentas é ativada por padrão: as ferramentas MCP são adiadas e descobertas sob demanda.

Definir CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS mantém a busca de ferramentas desativada. Você não pode sobrescrever isso definindo ENABLE_TOOL_SEARCH você mesmo. No Claude Code v2.1.227 ou posterior, sua organização pode manter a busca de ferramentas ativada sob essa variável através de configurações gerenciadas. Em uma sessão que recebe a configuração HIPAA, a busca de ferramentas fica desativada, e nem ENABLE_TOOL_SEARCH nem as configurações gerenciadas a reativam. Desativar capacidades de pré-lançamento cobre onde a substituição se aplica e o que a variável remove.

Claude Code usa a busca de ferramentas no Claude Opus 4, Claude Sonnet 4, Claude Haiku 4.5 e modelos posteriores, ou no Opus 4.5, Sonnet 4.5, Haiku 4.5 e modelos posteriores na Agent Platform do Google Cloud. Em modelos anteriores, Claude Code carrega todas as ferramentas MCP antecipadamente, e ENABLE_TOOL_SEARCH=true não sobrescreve isso.

Na Agent Platform do Google Cloud, Claude Code decide por geração de modelo:

• Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 e posteriores: a busca de ferramentas está ativada por padrão, o mesmo que na API Anthropic.
• Modelos anteriores da Agent Platform: Claude Code carrega todas as ferramentas MCP antecipadamente, porque suas pilhas de serviço rejeitam o cabeçalho beta necessário. ENABLE_TOOL_SEARCH=true não sobrescreve isso.

Controle o comportamento da busca de ferramentas com a variável de ambiente ENABLE_TOOL_SEARCH:

# Use a custom 5% threshold
ENABLE_TOOL_SEARCH=auto:5 claude

# Disable tool search entirely
ENABLE_TOOL_SEARCH=false claude

Ou defina o valor no campo env do seu settings.json.

Você também pode desativar a ferramenta ToolSearch especificamente:

{
  "permissions": {
    "deny": ["ToolSearch"]
  }
}

Se você negar ToolSearch ou deixá-la fora de --tools, as ferramentas MCP são carregadas antecipadamente, mas uma requisição ainda pode conter uma entrada defer_loading de espaço reservado. Se um gateway rejeitar essa entrada, consulte Busca de ferramentas através de um gateway de LLM.

Busca de ferramentas através de um gateway de LLM

[!NOTE]

Estes casos são abordados em outro lugar:

• Você definiu CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: veja como isso afeta a busca de ferramentas
• Uma requisição falhou com um erro que menciona defer_loading ou tool_reference: veja Extra inputs are not permitted

Quando ANTHROPIC_BASE_URL aponta para um gateway, Claude Code espera que o gateway encaminhe campos de ferramenta defer_loading e blocos tool_reference junto com o cabeçalho anthropic-beta. A busca de ferramentas está ativada por padrão atrás do gateway, então as ferramentas MCP são adiadas e as requisições incluem esses campos e blocos. Antes da v2.1.304, a busca de ferramentas ficava desativada atrás de um gateway, a menos que ENABLE_TOOL_SEARCH fosse true, auto ou auto:N.

Na v2.1.305 ou posterior, Claude Code pode tentar novamente uma requisição sem a busca de ferramentas após um 400 ou 422. Quando a nova tentativa funciona, nada aparece na tela e você não precisa fazer nada: as ferramentas MCP são carregadas antecipadamente. Claude Code tenta a busca de ferramentas novamente mais tarde, ao custo de outra requisição rejeitada.

Ferramentas que permanecem adiadas abaixo do limite de ENABLE_TOOL_SEARCH=auto

Se /context rotula ferramentas como (deferred) ou (loaded on-demand) embora suas definições totalizem menos que o limite auto, a busca de ferramentas já estava ativada nesta conversa e permaneceu ativada. O total pode cair mais tarde, por exemplo enquanto os servidores MCP se reconectam depois que você retoma uma sessão. Você não precisa fazer nada: Claude carrega cada uma dessas ferramentas quando uma tarefa precisa dela.

Isentar um servidor do adiamento

Se as ferramentas de um servidor devem estar sempre visíveis para Claude sem uma etapa de busca, defina alwaysLoad como true na configuração desse servidor. As ferramentas do servidor são então carregadas no contexto independentemente da configuração ENABLE_TOOL_SEARCH. Use isso para um pequeno número de ferramentas que Claude precisa a cada turno, pois cada ferramenta antecipada consome contexto que de outra forma estaria disponível para sua conversa.

A seguinte entrada .mcp.json isenta um servidor HTTP enquanto deixa outros servidores adiados:

{
  "mcpServers": {
    "core-tools": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "alwaysLoad": true
    }
  }
}

O campo alwaysLoad está disponível em todos os tipos de servidor.

Definir alwaysLoad: true também faz a inicialização aguardar as ferramentas do servidor, limitado ao timeout de conexão padrão de 5 segundos, pois elas devem estar presentes quando o primeiro prompt é construído. Um servidor remoto com uma entrada cached válida fornece suas ferramentas do cache sem se conectar, portanto não retarda a inicialização. Outros servidores se conectam em segundo plano por padrão; defina MCP_CONNECTION_NONBLOCKING=0 para fazer a inicialização aguardá-los também.

Adiar as ferramentas de um servidor

Para manter todas as ferramentas de um servidor atrás da busca de ferramentas, defina "alwaysLoad": false na entrada desse servidor em sua configuração MCP. Isso inclui ferramentas que o autor do servidor marcou para carregar antecipadamente. Se você omitir alwaysLoad, essas ferramentas marcadas são carregadas antecipadamente. Requer Claude Code v2.1.287 ou posterior.

Use MCP prompts as commands

MCP servers can expose prompts that become available as commands in Claude Code.

Prompts from a server named anthropic-skills don't appear, because Claude Code reserves that name for skills synced from claude.ai. The server's tools still work. Rename the server in your MCP configuration to list its prompts.

Execute MCP prompts

1. Discover available prompts

Type / to see the commands available to you, including those from MCP servers. Claude Code lists each MCP prompt as /servername:promptname (MCP). Typing /mcp__servername__promptname also runs it.

2. Execute a prompt without arguments

/mcp__github__list_prs

3. Execute a prompt with arguments

Many prompts accept arguments. Pass them space-separated after the command. Claude Code splits the arguments on whitespace, so each argument is a single token:

/mcp__github__pr_review 456

/mcp__jira__create_issue login-bug high

[!TIP]

Tips:

• MCP prompts are dynamically discovered from connected servers
• Arguments are parsed based on the prompt's defined parameters
• Prompt results are injected directly into the conversation
• In the /mcp__servername__promptname form, Claude Code replaces any character in the server name outside A-Z, a-z, 0-9, _, and - with _, and uses the prompt name as the server declares it

Configuração MCP gerenciada

Para organizações que precisam de controle centralizado sobre quais servidores MCP os usuários podem conectar, consulte Configuração MCP gerenciada. Ela aborda a implantação de um conjunto de servidor fixo com managed-mcp.json, fornecimento de servidores para cada usuário com managedMcpServers, restrição de servidores com allowedMcpServers e deniedMcpServers, e o que os usuários veem quando um servidor é bloqueado.