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.

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.

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

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

Instalando servidores MCP

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

Opção 1: Adicionar um servidor HTTP remoto

Os servidores HTTP são a opção recomendada para conectar a servidores MCP remotos. Este é o transporte mais amplamente suportado para serviços baseados em nuvem.

# Sintaxe básica
claude mcp add --transport http <name> <url>

# Exemplo real: Conectar ao Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Exemplo com token Bearer
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 um alias para http. A especificação MCP usa o nome streamable-http para este transporte, portanto as configurações copiadas da documentação do servidor funcionam sem modificação.

Uma entrada JSON que tem uma url mas nenhum type é um erro de configuração, porque Claude Code lê uma entrada sem type como um servidor stdio. Claude Code pula esse servidor e relata MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry. Antes da v2.1.202, Claude Code relatava essa configuração incorreta como command: expected string, received undefined.

Em execuções --output-format stream-json, Claude Code também relata uma entrada --mcp-config pulada no campo mcp_server_errors do evento system/init, para que scripts possam detectar que o servidor nunca foi carregado. Isso requer Claude Code v2.1.219 ou posterior.

Opção 2: Adicionar um servidor SSE remoto

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

Em uma versão anterior, ou para conectar sobre SSE diretamente, passe --transport sse em vez disso:

# Sintaxe básica
claude mcp add --transport sse <name> <url>

# Exemplo real: Conectar ao Asana
claude mcp add --transport sse asana https://mcp.asana.com/sse

# Exemplo com cabeçalho de autenticação
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 em sua máquina. Eles são ideais para ferramentas que precisam de acesso direto ao sistema ou scripts personalizados.

Claude Code define CLAUDE_PROJECT_DIR no ambiente do servidor gerado para a raiz do projeto, para que seu servidor possa resolver caminhos relativos ao projeto sem depender do diretório de trabalho. Este é o mesmo diretório que hooks recebem em sua variável CLAUDE_PROJECT_DIR. Leia-o de dentro do seu processo de servidor, por exemplo process.env.CLAUDE_PROJECT_DIR em Node ou os.environ["CLAUDE_PROJECT_DIR"] em Python.

CLAUDE_PROJECT_DIR é a raiz do projeto estável 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 solicitação MCP roots/list em vez disso. 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. Claude Code envia notifications/roots/list_changed quando esse conjunto muda. Antes da v2.1.203, roots/list retornava apenas o diretório de inicialização e Claude Code não enviava notifications/roots/list_changed.

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

# Sintaxe básica
claude mcp add [options] <name> -- <command> [args...]

# Exemplo real: Adicionar servidor Airtable
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

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 para Claude sem solicitação. Use HTTP em vez disso quando seu servidor apenas responde a solicitações, já que HTTP suporta OAuth e o sinalizador claude mcp add --transport, enquanto WebSocket não suporta 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 é apenas por cabeçalho, portanto passe um token estático em headers ou gere um no momento da conexão com headersHelper. O sinalizador 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, portanto as instruções de configuração de um servidor podem ser escritas para Claude Desktop, Cursor, ou outro cliente MCP e não fornecer nenhum comando claude mcp add. Para adicionar o servidor mesmo assim, procure nessas instruções por uma destas três coisas:

• 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 em sua máquina.
• Um bloco JSON mcpServers: configuração escrita para o arquivo de configurações de outro cliente.

Cada um é uma das entradas que as quatro opções em Instalando servidores MCP usam. Encontre a forma que você tem abaixo para transformá-la no comando que Claude Code aceita. Cada comando escreve no escopo local a menos que você adicione --scope project ou --scope user.

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 em vez disso, 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 cabeçalho de token, passe-o com --header como mostrado na Opção 1.

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 Claude Code passe sinalizadores como -y para o comando que inicia o servidor em vez de lê-los como suas próprias opções. Passe quaisquer variáveis de ambiente que as instruções peçam 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 cobre o separador -- completamente.

De um bloco JSON `mcpServers`

Um bloco mcpServers escrito para outro cliente MCP, como Claude Desktop, usa a chave wrapper e a forma de entrada que Claude Code lê. Passe claude mcp add-json o objeto dentro de mcpServers, não o wrapper. Duas entradas precisam de um reparo primeiro:

• Uma url sem type: adicione "type": "http", "type": "sse", ou "type": "ws" para corresponder ao endpoint. Claude Code lê uma entrada sem type como um servidor stdio, portanto uma entrada url sem type falha.
• Uma chave com caracteres diferentes de letras, números, hífens 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 cobre escape de shell e o sinalizador --scope para add-json. Para compartilhar o servidor com sua equipe em vez disso, adicione --scope project, ou adicione a entrada sob mcpServers em .mcp.json na raiz do seu projeto e faça commit. Escopo de projeto cobre como Claude Code carrega e aprova esse arquivo.

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

Gerenciando seus servidores

Uma vez configurados, você pode gerenciar seus servidores MCP com estes comandos:

# Listar todos os servidores configurados
claude mcp list

# Obter detalhes para um servidor específico
claude mcp get notion

# Remover um servidor
claude mcp remove notion

# (dentro do Claude Code) Verificar status do servidor
/mcp

Quando você remove um servidor remoto, Claude Code também exclui os tokens OAuth e o registro de cliente que armazenou para esse servidor.

Status do servidor

claude mcp add confirma uma adição bem-sucedida imprimindo uma linha Added ..., o que significa que a configuração foi escrita. claude mcp list então mostra um status de saúde ao lado de cada servidor que lista, como ✔ Connected, ! Needs authentication, ou ✘ Failed to connect. Um status de falha significa que Claude Code não conseguiu se conectar a esse servidor, não que o comando list falhou.

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

• ⏸ Pending approval (run `claude` to approve): um servidor com escopo de projeto de .mcp.json que você ainda não aprovou. Claude Code o mostra em claude mcp list e claude mcp get <name>. Execute claude interativamente para revisar e aprovar.
• ✘ Rejected (see disabledMcpjsonServers in settings): um servidor .mcp.json que uma entrada disabledMcpjsonServers rejeita. 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. Claude Code o mostra em claude mcp list e claude mcp get <name>. Ative o servidor novamente no painel /mcp. Antes da v2.1.238, ambos os comandos se conectavam a um servidor desabilitado para verificar sua saúde e relatavam o resultado da conexão.

Os servidores WebSocket não aparecem na saída de claude mcp list. Use claude mcp get <name> ou o painel /mcp para verificá-los.

Aprovações de servidor de projeto e confiança do workspace

A partir da v2.1.196, claude mcp list e claude mcp get leem aprovações .mcp.json apenas de arquivos de configurações que não são verificados no repositório até que você confie no workspace executando claude nele e aceitando o diálogo de confiança do workspace. Um repositório clonado não pode aprovar seus próprios servidores: enableAllProjectMcpServers ou enabledMcpjsonServers confirmados no .claude/settings.json do projeto é ignorado em uma pasta não confiável, e o servidor permanece em ⏸ Pending approval em vez de ser conectado e verificado quanto à saúde.

As aprovações dessas 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

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

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

Detalhe do status do servidor

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

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

Duas ações no menu de um servidor em /mcp também afetam a entrada de cache desse servidor:

• Reconnect: em um servidor cached, Claude Code o conecta agora em vez de em sua primeira chamada de ferramenta e mantém a entrada. Em um servidor conectado ou com falha, Claude Code o reconecta e também descarta a entrada.
• Clear authentication: Claude Code revoga a autenticação do servidor e também descarta a entrada.

Após descartar a entrada, Claude Code busca a lista de ferramentas do servidor do servidor em vez de do cache.

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 status HTTP ou código de erro, mais qualquer texto de erro que o servidor retornou. A visualização de detalhe do servidor em /mcp inclui o mesmo texto relatado pelo servidor em sua linha Issue:. Claude Code redige texto semelhante a credenciais deste detalhe e nunca inclui a URL do servidor expandida, que pode carregar segredos. Claude Code não acrescenta detalhe a um status ✘ Connection error, porque o texto de exceção que imprimiria lá pode incorporar essa URL. Antes da v2.1.219, ambos os comandos mostravam apenas o status de falha simples, sem o código de status ou o texto de erro do servidor.

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

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

Um servidor remoto cuja configuração tem uma url vazia mostra como not configured em /mcp, em claude mcp list, e no gerenciador /plugin, e 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, portanto Claude Code não a relata como um erro ou um problema de configuração. A visualização de detalhe do servidor em /mcp lê No URL configured for this server; defina a url da entrada para conectá-lo. Antes da v2.1.208, Claude Code relatava uma url vazia como um problema de configuração com um prompt para reconectar.

Avisos de configuração

Claude Code avisa sobre os problemas de configuração abaixo. Cada entrada diz o que Claude Code verifica e como limpar o aviso:

• Espaço em branco oculto: Claude Code avisa quando um valor de configuração MCP carrega espaço em branco oculto à esquerda ou à direita, que frequentemente vem de colar um token com uma quebra de linha à direita. Claude Code verifica command, url, cada entrada args, e os valores e nomes de chave sob env e headers. Claude Code mostra o aviso na saída de claude mcp list e em /mcp, nomeando os campos afetados sem ecoar seus valores, por exemplo Leading or trailing whitespace in: headers.Authorization. Claude Code não aparenta o espaço em branco e usa os valores exatamente como escritos, portanto edite a configuração para removê-lo.
• Mesmo nome em mais de um escopo: se você definir o mesmo nome de servidor em mais de um escopo com endpoints diferentes, Claude Code avisa sobre o conflito na saída de claude mcp list e em /mcp. Claude Code armazena logins OAuth por endpoint, portanto quando você autentica a definição que carrega em um projeto, você ainda precisa fazer login separadamente em um projeto onde uma definição diferente carrega. Mantenha o endpoint que você quer e remova os outros com claude mcp remove <name> --scope <scope>. No aviso, Claude Code cita o endpoint de cada escopo como escrito em sua configuração, com referências ${VAR} não expandidas, portanto nunca mostra um valor resolvido como uma chave de API.
• Nomes reservados: 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, Claude Code o pula no tempo de 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 ambos nomeiam o servidor integrado que o painel de visualização do aplicativo de desktop Claude Code usa. Antes da v2.1.205, Claude Browser não era reservado, portanto um servidor configurado pelo usuário poderia se registrar sob esse nome.
• Variável de ambiente ausente: se uma referência ${VAR} na configuração de um servidor nomeia uma variável que não está definida e não tem :-default, Claude Code avisa 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}. Em uma URL remota do servidor e headers, algumas variáveis de credenciais leem como vazias em vez disso, 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 ferramentas.

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

• Com busca de ferramentas, o padrão: a espera acontece dentro da chamada ToolSearch.
• Sem busca de ferramentas: Claude usa a ferramenta WaitForMcpServers em vez disso. As configurações sem busca de ferramentas incluem um ANTHROPIC_BASE_URL personalizado, ENABLE_TOOL_SEARCH=false, e um modelo anterior à geração Claude 4.5 na Agent Platform do Google Cloud.
• Em uma implantação Microsoft Foundry hospedada no Azure: Claude começa no caminho de busca de ferramentas em vez de com WaitForMcpServers, já que Claude Code descobre a rejeição do lado do servidor apenas da API. Depois que 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 solicitação do Claude.

Com busca de ferramentas ativada, quando um servidor termina de se conectar enquanto Claude está trabalhando, Claude Code lista os nomes de ferramentas do servidor para Claude em sua próxima solicitação no mesmo turno. Claude pode então procurar e chamar essas ferramentas sem aguardar sua próxima mensagem.

Desabilitar um servidor sem removê-lo

Alterne um servidor no painel /mcp para impedir que Claude Code se conecte a ele sem perder sua configuração. Claude Code ainda lista o servidor em /mcp, marcado como desabilitado.

Quando você alterna um servidor, 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 plugin, servidores que sua organização fornece através de configurações gerenciadas, os conectores claude.ai que Claude Code busca a si mesmo, e servidores integrados que padrão para ativado. Claude Code não se conecta a um servidor que você lista aqui. Quando você desabilita um conector claude.ai com o alternador /mcp por projeto descrito em Desabilitar conectores claude.ai, Claude Code o escreve nesta lista sob seu nome de exibição, por exemplo claude.ai Slack.
• enabledMcpServers: uma lista de inclusão para servidores integrados que padrão para desabilitado, como computer-use. Claude Code se conecta a um servidor padrão-desabilitado apenas quando você o lista aqui.

Claude Code consulta exatamente uma das duas listas para cada servidor, portanto nenhuma lista substitui a outra. Se você adicionar um servidor regular a enabledMcpServers, ou um servidor integrado padrão-desabilitado a disabledMcpServers, Claude Code ignora a entrada.

disabledMcpServers e enabledMcpServers não estão relacionados a enabledMcpjsonServers e disabledMcpjsonServers, que controlam a aprovação de servidores definidos no arquivo .mcp.json de um projeto.

MCP client runtimes

Claude Code se conecta a servidores MCP através de um de dois tempos de execução do cliente. O tempo de execução v1 é construído no MCP TypeScript SDK 1.x. O tempo de execução v2 é o mesmo código no MCP TypeScript SDK 2.0, que adiciona revisão de protocolo MCP 2026-07-28. O resto desta página se aplica a ambos os tempos de execução, exceto onde uma seção nomeia o tempo de execução v2.

Claude Code escolhe um tempo de execução cada vez que você o inicia e o mantém até você sair. Em sessões onde ele busca sinalizadores de recurso, ele usa o tempo de execução v2 no Claude Code v2.1.232 ou posterior.

Nas sessões onde ele não busca sinalizadores de recurso, Claude Code usa o tempo de execução v2 por padrão no Claude Code v2.1.274 ou posterior:

• Sessões no Amazon Bedrock, Claude Platform no AWS, Agent Platform do Google Cloud, ou Microsoft Foundry, a menos que uma plataforma host que incorpora Claude Code defina CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST
• Sessões conectadas através de um gateway de aplicativos Claude
• Sessões onde você desativa telemetria ou busca de sinalizador de recurso, por exemplo com DISABLE_TELEMETRY

No v2, Claude Code também:

• Pergunta aos servidores HTTP se eles suportam a revisão mais recente, e a usa com aqueles que fazem. Ele também pergunta aos servidores conectores claude.ai em sessões onde ele busca sinalizadores de recurso. Para tê-lo perguntar aos servidores stdio, ou aos servidores conectores em cada sessão, defina MCP_PROTOCOL_NEGOTIATION como auto. Ele se conecta a todos os outros servidores como v1 faz.
• Recebe notificações list_changed de servidores na revisão mais recente sobre um stream que mantém aberto.
• Não registra um servidor channel que se conecta na revisão mais recente, porque essa revisão não pode carregar mensagens de canal.
• Falha em um login OAuth MCP cuja resposta de autorização nomeia um emissor inesperado.

Anthropic pode manter um servidor específico no protocolo anterior, ou fora desse stream, com um sinalizador de recurso que Claude Code busca.

Para escolher o tempo de execução você mesmo, defina MCP_SDK_GENERATION como v1 ou v2. Para decidir se Claude Code pergunta, defina MCP_PROTOCOL_NEGOTIATION como auto ou legacy.

Dynamic tool updates

Claude Code suporta notificações MCP list_changed, permitindo que servidores MCP atualizem dinamicamente suas ferramentas, prompts e recursos disponíveis sem exigir que você se desconecte e reconecte. Quando um servidor MCP envia uma notificação list_changed, Claude Code atualiza automaticamente as capacidades disponíveis desse servidor.

Se uma solicitação de atualização falhar, Claude Code mantém as ferramentas, prompts e recursos descobertos anteriormente do servidor até que uma atualização posterior tenha sucesso. Antes da v2.1.214, um erro transitório durante a atualização substituía as ferramentas, prompts e recursos do servidor por uma lista vazia.

Notification streams on the v2 runtime

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

• O stream fecha novamente dentro de 10 segundos: Claude Code o reabre até três vezes, depois para para essa conexão.
• O stream permanece aberto por mais de 10 segundos, depois fecha, como streams para hosts sem servidor comumente fazem: após cinco reabertas em uma hora, Claude Code aguarda cerca de seis horas antes da próxima.

Até o stream reabrir, você mantém as ferramentas, prompts e recursos buscados pela última vez do servidor. Para pegar suas mudanças mais cedo, reconecte o servidor de /mcp.

Automatic reconnection

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. Os servidores Stdio são processos locais, e Claude Code não os reconecta automaticamente.

Mid-session drops of a remote server

Claude Code reconecta um servidor remoto caído com backoff exponencial: até cinco tentativas, começando com um atraso de um segundo e dobrando a cada vez. O que você vê depende de como você está executando Claude Code:

• Em uma sessão interativa: /mcp mostra o servidor como pendente enquanto Claude Code reconecta. Após cinco tentativas falhadas, Claude Code marca o servidor como com falha, ou como precisando de autenticação quando o servidor precisa ser autorizado novamente. Você pode tentar novamente manualmente de /mcp.
• Em execuções claude -p e sessões Agent SDK: Claude Code reconecta no mesmo cronograma, sem painel /mcp para mostrar as tentativas.

Failed first connections

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 tempo limite, Claude Code tenta novamente até três vezes. Se a conexão ainda falhar, Claude Code marca o servidor como com falha. Claude Code tenta novamente dessa forma na inicialização e quando um servidor é adicionado no meio da sessão. Isso inclui um servidor que Claude Code adiciona a uma sessão em nuvem de sua configuração e um servidor que você adiciona com o setMcpServers() do Agent SDK.

Claude Code não tenta novamente nestes casos:

• Primeira conexão de um servidor WebSocket
• Um erro de autenticação ou não encontrado, porque requer uma mudança de configuração para resolver. Quando um headersHelper é a única fonte do servidor do cabeçalho Authorization, Claude Code tenta novamente um erro de autenticação mesmo assim, porque re-executa o helper em cada tentativa e pode pegar uma credencial fresca

Failed discovery requests

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

How Claude learns that a server failed

Se Claude Code diz a Claude sobre um servidor configurado que falhou em se conectar depende de busca de ferramentas, que está ativada por padrão:

• Com busca de ferramentas, Claude Code diz a Claude qual servidor falhou e seu erro de conexão, portanto Claude relata a falha de conexão em sua resposta. Claude Code inclui as mesmas informações nos resultados de ToolSearch que não encontram nenhuma ferramenta correspondente.
• Em qualquer configuração sem busca de ferramentas, Claude Code não relata falhas de conexão de servidor com falha a Claude.

Push messages with channels

Um servidor MCP também pode enviar mensagens diretamente para sua sessão para que Claude possa reagir a eventos externos como resultados de CI, alertas de monitoramento, ou mensagens de chat. Para ativar isso, seu servidor declara a capacidade claude/channel e você o ativa com o sinalizador --channels na inicialização. Veja Channels para usar um canal oficialmente suportado, ou Channels reference para construir o seu próprio.

No tempo de execução v2, se você definir MCP_PROTOCOL_NEGOTIATION como auto e um servidor de canal negocia revisão de protocolo MCP 2026-07-28, ele não pode entregar mensagens de canal, portanto Claude Code não o registra como um canal. Deixar a variável não definida, ou defini-la como legacy, mantém servidores stdio no handshake anterior.

O timeout por servidor é um limite de parede de relógio duro por chamada de ferramenta, e notificações de progresso do servidor não o estendem. Valores abaixo de 1000 são ignorados e caem para MCP_TOOL_TIMEOUT, ou para seu padrão de cerca de 28 horas quando essa variável não está definida. Para um servidor HTTP, SSE, ou conector claude.ai há também um segundo temporizador por solicitação que cobre cada solicitação até o primeiro byte de resposta do servidor. Claude Code define esse temporizador para o maior de três valores: 60 segundos, o tempo limite 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. Os servidores Stdio e WebSocket não têm temporizador por solicitação.

Um timeout por servidor de pelo menos 1000 também atua como um piso no tempo limite de inatividade descrito abaixo: Claude Code nunca aborta as chamadas de ferramenta desse servidor por inatividade mais cedo do que o timeout por servidor. Requer Claude Code v2.1.203 ou posterior.

Uma chamada de ferramenta para um servidor MCP que não envia resposta e nenhuma notificação de progresso para a janela de inatividade aborta com um erro em vez de aguardar o limite de parede de relógio. O tempo limite de inatividade requer Claude Code v2.1.187 ou posterior. Aplica-se a todos os tipos de servidor exceto servidores IDE e SDK em processo. A janela de inatividade padrão é de cinco minutos para servidores HTTP, SSE, WebSocket, e conector claude.ai, e de 30 minutos para servidores stdio. Antes da v2.1.203, servidores stdio eram isentos do tempo limite de inatividade.

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 desabilitar a verificação.

Esses tempos limite limitam quanto tempo uma chamada pode ser executada, nem sempre quanto tempo bloqueia a sessão: uma chamada de conversa principal que é executada por mais de dois minutos se move para uma tarefa em segundo plano primeiro. Veja Automatic backgrounding of long tool calls.

Automatic backgrounding of long tool calls

Uma chamada de ferramenta MCP na conversa principal que ainda está em execução após dois minutos se move para uma tarefa em segundo plano em vez de bloquear a sessão. Claude recebe o ID da tarefa imediatamente e continua trabalhando, e o resultado chega como uma notificação de tarefa quando a chamada se resolve. O backgrounding automático requer Claude Code v2.1.212 ou posterior.

A tarefa aparece em /tasks, onde você também pode pará-la, e não sobrevive ao sair da sessão. Os limites por chamada ainda se aplicam enquanto a chamada é executada em segundo plano: o limite de parede de relógio definido pelo timeout por servidor ou MCP_TOOL_TIMEOUT, e o tempo limite de inatividade definido por CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT.

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 backgrounding automático. Definir CLAUDE_CODE_DISABLE_BACKGROUND_TASKS como 1 também o desativa, junto com todos os outros recursos de tarefa em segundo plano.

Algumas chamadas nunca se movem para o segundo plano:

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

Uma chamada aguardando um diálogo de elicitação aberto não é colocada em segundo plano enquanto o diálogo está aberto; o servidor está bloqueado em sua entrada, não lento, portanto Claude Code adia a mudança até o diálogo fechar.

Plugin-provided MCP servers

Plugins podem agrupar servidores MCP que fornecem ferramentas e integrações quando você ativa o plugin. Os servidores MCP de plugin funcionam de forma idêntica aos servidores configurados pelo usuário.

Como funcionam os servidores MCP de plugin:

• Plugins definem servidores MCP em .mcp.json na raiz do plugin ou inline em plugin.json
• Quando você ativa um plugin, Claude Code inicia seus servidores MCP automaticamente
• Claude Code oferece ferramentas MCP de plugin ao lado de ferramentas MCP configuradas manualmente
• Você adiciona e remove servidores de plugin instalando ou desinstalando o plugin, não com comandos /mcp. Você ainda pode alternar um servidor de plugin instalado desativado em /mcp, o que impede que Claude Code se conecte 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 plugin:

• Ciclo de vida automático: servidores se conectam e desconectam nestes pontos:
  • Na inicialização da sessão, Claude Code conecta os servidores para plugins ativados automaticamente. Em /mcp, um servidor de plugin remoto (HTTP ou SSE) que você usou antes pode mostrar o status cached em vez disso; Claude Code o conecta quando Claude chama pela primeira vez uma de suas ferramentas
  • Se você ativar ou desativar um plugin durante uma sessão, Claude Code conecta ou desconecta seus servidores MCP quando a mudança se aplica. Apply plugin changes without restarting descreve quando isso é. Em uma sessão sem um terminal interativo, /reload-plugins não conecta ou desconecta servidores MCP de plugin; essas mudanças entram em vigor em sua próxima sessão
  • Quando você recarrega, Claude Code mantém as conexões ativas de servidores de plugin cuja configuração não mudou, e faz o mesmo quando você substitui a lista de servidores MCP da sessão do Agent SDK sem nomeá-los
  • Quando você move a sessão com /cd na v2.1.246 ou posterior, Claude Code conecta os servidores de plugins que as configurações do novo diretório ativam e desconecta os servidores de plugins que não estão mais ativados, portanto você não precisa executar /reload-plugins após a mudança
  • Em sessões web, uma chamada MCP para um servidor de plugin que ainda não está conectado, como logo após uma sessão ociosa acordar, inicia o servidor sob demanda e aguarda sua conexão
• Espaços reservados 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 do projeto estável. A substituição se aplica a:
  • servidores stdio: command, args, env
  • servidores http, sse, e ws: url, headers, e headersHelper. Antes da v2.1.195, headersHelper passava o espaço reservado como uma string literal
• Acesso ao ambiente do usuário: acesso às mesmas variáveis de ambiente que servidores configurados manualmente
• Múltiplos tipos de transporte: suporte para transportes stdio, SSE, HTTP, e WebSocket, embora o suporte de transporte possa variar por servidor

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

Nomes de ferramentas MCP de plugin:

As ferramentas de um servidor MCP agrupado em plugin incluem 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>, onde qualquer caractere fora de A-Z, a-z, 0-9, _, e - é substituído por _. Para o servidor database-tools agrupado em um plugin nomeado my-plugin, uma ferramenta query é chamável como:

mcp__plugin_my-plugin_database-tools__query

Use este nome completo ao fazer referência à ferramenta em regras de permissão, lista allowed-tools de uma skill, campo tools de um subagente, ou matcher de hook. Um matcher de hook escrito contra a chave do servidor simples, como mcp__database-tools__.*, nunca dispara para um servidor agrupado em plugin.

O servidor em si se registra sob o nome com escopo plugin:<plugin-name>:<server-name>, como plugin:my-plugin:database-tools. Use esse nome onde um nome de servidor configurado é esperado, como um campo server de hook mcp_tool.

Veja a referência de componentes de plugin para detalhes sobre agrupamento de servidores MCP com 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.

# 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, 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

Os três escopos correspondem duplicatas por nome. Plugins e conectores correspondem por endpoint, então um que aponta para a mesma URL ou comando que um servidor acima é tratado como uma duplicata.

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.

Sintaxe suportada

• ${VAR}: expande para o valor da variável de ambiente VAR
• ${VAR:-default}: expande para VAR se definida, caso contrário usa default

Locais de expansão

As variáveis de ambiente podem ser expandidas em:

• command: o caminho do executável do servidor
• args: argumentos de linha de comando
• env: variáveis de ambiente passadas para o servidor
• url: para tipos de servidor HTTP
• headers: para autenticação de servidor HTTP

Exemplo com expansão de variável

{
  "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 necessária 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. Em uma URL e headers de servidor remoto, algumas variáveis de credencial leem como vazias em vez disso, sem aviso.

Variáveis de credencial que leem como vazias

Em uma URL e headers de 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 solicitaçã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 headers de um servidor remoto referencia 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 o servidor mostra connected. Um servidor com credenciais inválidas mostra failed, e o 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 db mostra connected.

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. Claude Code suporta OAuth 2.0 para conexões seguras.

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

• Para um servidor no qual você ainda não fez login, qualquer código de status o sinaliza em /mcp para que você possa completar o fluxo OAuth.
• Para um conector claude.ai, um 401 causado por claude.ai rejeitando seu token de sessão não sinaliza o conector, porque re-autorizar o conector não pode corrigir seu login. Claude Code mostra o estado de token de sessão rejeitado em vez disso.
• Para um servidor cujo cabeçalho Authorization você configurou, em headers ou através de um headersHelper, um 401 ou 403 ao conectar não sinaliza o servidor, porque a credencial a corrigir é a que você configurou. Claude Code relata a conexão como falha em vez disso. Se você definiu esse cabeçalho a partir de uma referência ${VAR}, verifique se essa variável é uma que Claude Code lê como vazia.
• Para um conector entregue a uma sessão em nuvem, 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 em claude.ai. Quando um conector lá precisa ser autorizado novamente, reconecte-o em claude.ai/customize/connectors em vez de a partir da sessão.

Quando uma solicitação para um servidor OAuth no qual você já fez login retorna 401 Unauthorized, Claude Code atualiza o token armazenado, reconecta e tenta a solicitação novamente uma vez. Ele sinaliza o servidor em /mcp apenas se essa tentativa também falhar. Antes da v2.1.206, uma atualização de token que falhava por um motivo transitório, como um erro de rede, sinalizava um servidor OAuth como necessitando autenticação pelo resto da sessão, mesmo que seu token de atualização ainda fosse válido.

Quando o servidor rejeita o token de atualização armazenado, Claude Code imediatamente mostra um aviso apontando para /mcp. Abra /mcp e selecione Re-autenticar 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 obtém a mesma descoberta automática que qualquer outro servidor remoto.

Claude Code também mostra um aviso de inicialização quando um ou mais servidores configurados precisam de autenticação, para que você não tenha que abrir /mcp para descobrir quais servidores precisam de login. O aviso requer Claude Code v2.1.193 ou posterior. Ele conta apenas servidores nos quais você pode fazer login a partir do Claude Code. Antes da v2.1.218, ele também contava conectores claude.ai que não estavam conectados em claude.ai, que você pode conectar apenas a partir das configurações de claude.ai.

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

No modo não interativo não há painel /mcp, então Claude Code não pode executar o fluxo OAuth para você. A partir da v2.1.196, quando um servidor configurado precisa de autenticação durante uma execução claude -p ou Agent SDK com busca de ferramentas ativada, que é o padrão, Claude Code informa ao Claude que as ferramentas do servidor estão indisponíveis até que você o autorize. Claude pode então nomear o servidor que precisa de login em vez de responder como se o servidor não estivesse configurado. Complete o login de uma sessão interativa com /mcp ou claude mcp login <name>.

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

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

/mcp

Autenticar a partir da linha de comando

A partir da v2.1.186, 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.

claude mcp login sentry

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

A partir da v2.1.191, o comando 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, depois 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 colagem, então conecte com ssh -t. Passe --no-browser para forçar o prompt de URL mesmo quando um navegador local é 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 antecipadamente. Por padrão, Claude Code escolhe uma porta aleatória disponível para o callback OAuth. Use --callback-port para fixar a porta para que corresponda a um URI de redirecionamento pré-registrado do formulário http://localhost:PORT/callback. Se o login em 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).

# Porta de callback fixa com registro dinâmico de cliente
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 suportam configuração automática de OAuth via Registro Dinâmico de Cliente. Se você vir um erro como "Incompatible auth server: does not support dynamic client registration," o servidor requer credenciais pré-configuradas. Claude Code também suporta servidores que usam um Documento de Metadados de ID do Cliente (CIMD) em vez de Registro Dinâmico de Cliente, e descobre esses automaticamente. Se a descoberta automática falhar, registre um aplicativo OAuth através do portal do desenvolvedor do servidor primeiro, depois forneça as credenciais ao adicionar o servidor.

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

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

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

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

Substituir descoberta de metadados OAuth

Aponte Claude Code para uma URL de metadados específica de servidor de autorização OAuth para contornar a cadeia de descoberta padrão. Defina authServerMetadataUrl quando os endpoints padrão do servidor MCP falharem, ou quando você deseja rotear a descoberta através de um proxy interno. Por padrão, Claude Code primeiro verifica os Metadados de Recurso Protegido RFC 9728 em /.well-known/oauth-protected-resource, depois volta para os metadados do servidor de autorização RFC 8414 em /.well-known/oauth-authorization-server.

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

{
  "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://. Os scopes_supported da URL de metadados substituem os escopos que o servidor upstream anuncia.

Restringir escopos OAuth

Defina oauth.scopes para fixar os escopos que Claude Code solicita durante o fluxo de autorização. Esta é a forma suportada de restringir um servidor MCP a um subconjunto aprovado pela equipe de segurança quando o servidor de autorização upstream anuncia mais escopos do que você deseja conceder. O valor é uma única string separada por espaço, correspondendo ao formato do parâmetro scope em RFC 6749 §3.3.

{
  "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 os escopos que o servidor descobre em /.well-known. Deixe-o indefinido para permitir que o servidor MCP determine o conjunto de escopos solicitado.

A partir da v2.1.196, quando oauth.scopes não está definido, Claude Code solicita o escopo fornecido pelo cabeçalho WWW-Authenticate do servidor ou seus metadados de recurso protegido, e não envia nenhum parâmetro scope quando nenhum dos dois fornece um. Ele não solicita mais o catálogo completo de scopes_supported dos metadados do servidor de autorização descobertos automaticamente. Solicitar esse catálogo fez com que provedores de identidade que anunciam escopos apenas para administrador ou escopos de modelo rejeitassem a solicitação de autorização com um erro invalid_scope. Os metadados obtidos de um authServerMetadataUrl configurado ainda fornecem seus scopes_supported como os escopos solicitados.

Se o servidor de autorização anuncia offline_access em scopes_supported, Claude Code o acrescenta aos escopos fixados para que o token de acesso possa ser atualizado sem um novo login no navegador.

Se o servidor depois retorna um 403 insufficient_scope para uma chamada de ferramenta, a chamada falha com uma mensagem precisa de permissões adicionais que nomeia o escopo que o servidor solicita. O servidor aparece como necessitando autenticação em /mcp.

Se esse escopo não estiver em seu oauth.scopes fixado, adicione-o, depois execute /mcp e autentique o servidor novamente. 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 ainda não o possui.

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

Se seu servidor MCP usar um esquema de autenticação diferente de OAuth, como Kerberos, tokens de curta duração ou um SSO interno, use headersHelper para gerar cabeçalhos de solicitação no momento da conexão. Claude Code executa o comando e mescla sua saída nos cabeçalhos de conexão.

{
  "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 um objeto JSON de pares chave-valor de string para stdout
• Claude Code executa o comando em um shell e desiste dele após 10 segundos
• Claude Code escolhe o diretório de trabalho do comando por onde você configurou o servidor, então forneça o script como um caminho absoluto ou coloque-o em PATH
• Cabeçalhos dinâmicos substituem qualquer headers estático com o mesmo nome

Claude Code executa o auxiliar novamente em cada conexão, no início da sessão e ao reconectar, uma vez que a regra de confiança para servidores de escopo de projeto e local permite que ele seja executado. Ele não armazena em cache o resultado, então seu script é responsável por qualquer reutilização de token.

Se uma chamada de ferramenta retorna 401 Unauthorized ou 403 Forbidden, Claude Code automaticamente executa novamente o auxiliar sob a mesma regra, reconecta com os cabeçalhos atualizados e tenta novamente a chamada uma vez. Claude Code marca o servidor como necessitando autenticação em /mcp apenas se essa tentativa também falhar.

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

Se o servidor rejeita a credencial do auxiliar ao conectar, Claude Code relata a conexão como falha em vez de marcar o servidor como necessitando autenticação. Corrija a credencial que seu auxiliar retorna, depois reconecte de /mcp para executar novamente o auxiliar.

Claude Code define essas variáveis de ambiente ao executar o auxiliar:

Use essas para escrever um único script auxiliar que serve múltiplos servidores MCP.

Um headersHelper fornecido por plugin não pode referenciar os valores ${user_config.*} do plugin, porque o comando é executado através de um shell. Claude Code relata o servidor como mal configurado com um erro e não substitui o valor. Coloque ${user_config.KEY} no campo headers do servidor, que não é analisado por shell, ou faça o script auxiliar ler o valor de um arquivo de configuração. Antes da v2.1.207, headersHelper substituía valores ${user_config.*}.

Onde o auxiliar é executado

Claude Code escolhe o diretório de trabalho do comando headersHelper a partir da configuração que declara o servidor. Um cd que Claude executa em Bash não o move, e /cd o move apenas para servidores que são executados a partir do diretório de trabalho primário da sessão. Cada linha abaixo fornece o diretório contra o qual um caminho relativo em seu comando headersHelper é resolvido.

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

Quais variáveis um auxiliar pode ler

Um headersHelper que um repositório ou plugin fornece é um comando que você não escreveu, então Claude Code o executa sem as variáveis de credencial 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 de seu projeto ou de um diretório --add-dir
• Não removidas: um servidor em escopo de usuário ou escopo local, em MCP gerenciado, de um conector claude.ai, ou fornecido pelo SDK ou --mcp-config, e um servidor inline em um arquivo de agente de ~/.claude/agents/, de configurações gerenciadas, ou passado com --agents

Além das variáveis GIT_CONFIG_KEY_<n> do Git, Claude Code remove todas as variáveis do seu ambiente cujo nome parece uma credencial, como um nome com TOKEN, SECRET, PASSWORD, KEY, ou AUTH nele em qualquer caso de letra, então ANTHROPIC_API_KEY e MY_REGISTRY_TOKEN são ambos removidos. Claude Code também remove uma lista fixa de variáveis de credencial cujos nomes não seguem esse padrão, como ANTHROPIC_CUSTOM_HEADERS.

Quando isso se aplica ao seu auxiliar, faça o script ler sua credencial de um arquivo ou de um armazenamento de credenciais. Se a url do servidor expande uma dessas variáveis, o valor CLAUDE_CODE_MCP_SERVER_URL que o auxiliar recebe tem essa parte substituída por REDACTED também.

Confiar em uma pasta antes de seu headersHelper ser executado

Claude Code executa um headersHelper como um comando shell arbitrário. Para um servidor em um .mcp.json de projeto ou em escopo local, ele executa o auxiliar apenas após você aceitar o diálogo de confiança para o diretório do projeto no qual o servidor é declarado. Antes da v2.1.238, uma sessão claude -p ou SDK executava esses auxiliares sem verificar confiança, e uma sessão interativa os executava uma vez que você tinha confiado em uma pasta pai.

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

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

Adicionar servidores MCP de configuração JSON

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

# 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

claude mcp get weather-api

Importar servidores MCP do Claude Desktop

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

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

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. Antes da v2.1.205, o primeiro nome inválido interrompia a importação e nenhum dos servidores selecionados era adicionado.

Usar servidores MCP do claude.ai

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

/mcp

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

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

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 se você executou /login anteriormente, quando:

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

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

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

Se /mcp mostrar um conector como connected · session token rejected, ou sua visualização de detalhes mostrar claude.ai rejected the session token, o claude.ai rejeitou o token de seu login do Claude Code, geralmente porque o login expirou e não pôde ser atualizado. Autorizar o conector novamente não limpa esse estado, porque a autorização própria do conector no claude.ai não é o que foi rejeitado. Para limpá-lo:

1. Execute /login para fazer login novamente.
2. Reconecte o conector de /mcp.

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

Um servidor que você adicionou no Claude Code tem precedência sobre um conector claude.ai que aponta para a mesma URL. Quando isso acontece, /mcp lista o conector como oculto e mostra como remover a duplicata se você preferir usar o conector.

Alguns conectores hospedados pela Anthropic, como Microsoft 365, Gmail e Google Calendar, não suportam OAuth local 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 de /mcp ou com claude mcp login, o Claude Code mostra is Anthropic-hosted and doesn't support local OAuth, direcionando você para conectar o serviço em claude.ai/customize/connectors.

Depois de remover sua entrada com claude mcp remove <name> e conectar o serviço no claude.ai, o conector aparece no Claude Code automaticamente.

Como os conectores chegam ao Claude Code

Quais configurações governam um conector claude.ai depende de onde sua sessão é executada, porque apenas algumas sessões buscam conectores do claude.ai. Cada linha abaixo nomeia como os conectores chegam em um tipo de sessão e o que os controla lá. As sessões WSL do aplicativo desktop não têm uma linha porque os conectores ainda não estão disponíveis nelas.

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

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

Controles de organização em ferramentas de conector

Sua organização pode definir controles por ferramenta em conectores 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. Lá, o aplicativo desktop retém ferramentas blocked antes de entregar um conector, e a configuração ask não chega ao Claude Code, então ele aplica as regras de permissão ordinárias da sessão a essas ferramentas em vez de solicitar a cada chamada. Em sessões onde o Claude Code busca conectores, execute /mcp para ver qual configuração se aplica a cada ferramenta em um conector.

• Ferramenta definida como ask: O Claude Code solicita a cada chamada com o motivo Your organization requires approval for this tool. O prompt aparece mesmo em modos de permissão acceptEdits, auto e bypassPermissions, e nunca oferece uma opção para lembrar sua escolha. Regras de permissão que correspondem à ferramenta também não pulam o prompt. No modo dontAsk, que nunca solicita, o Claude Code nega a chamada.
• Ferramenta definida como blocked: O Claude Code filtra a ferramenta antes de Claude vê-la, então ela nunca aparece na lista de ferramentas. O aplicativo desktop e o chat claude.ai aplicam a mesma configuração blocked, então Claude não pode usar a ferramenta lá também, 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 pula um conector cujas ferramentas estão todas bloqueadas.

Desabilitar conectores claude.ai

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

{
  "disableClaudeAiConnectors": true
}

Esta configuração usa semântica any-source-true: true em qualquer fonte de configurações tem precedência. Um .claude/settings.json de projeto verificado pode optar um repositório pelos conectores que o Claude Code busca, mas um false em nível de projeto não pode reabilitar conectores que um true em nível de usuário ou política desabilitou. 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, que tem o mesmo efeito para a sessão de shell atual:

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

Para bloquear conectores claude.ai individuais 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 Slack. Você também pode executar /mcp para alternar qualquer conector que o Claude Code busca ativado ou desativado 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": {}
    }
  }
}

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 sem conteúdo de imagem excede o limite, 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/.

Para aumentar o limite para ferramentas que produzem grandes saídas:

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, 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 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.

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. Versões anteriores à v2.1.195 pulam todas as ferramentas cujo esquema de entrada tem um anyOf, oneOf ou allOf no nível raiz.

Ferramentas com esquemas de entrada inválidos

A API Claude verifica o esquema de entrada de cada ferramenta em uma solicitação e rejeita toda a solicitação quando qualquer esquema falha, portanto uma única ferramenta MCP com um esquema malformado faria com que toda solicitação que a inclua falhasse com um erro 400. Claude Code executa duas das verificações da API por conta própria quando carrega as ferramentas de um servidor e exclui cada ferramenta que falharia nelas, para que as outras ferramentas do servidor continuem funcionando:

• 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

Claude Code executa as verificações após a reescrita do combinador de nível raiz, no esquema que realmente enviaria.

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.

Claude Code ativa a exclusão através de um sinalizador de recurso que busca da Anthropic. Em uma implantação onde a busca de sinalizadores está desativada, ou em uma máquina cujos sinalizadores nunca chegaram, como uma máquina isolada, Claude Code ainda executa as verificações e registra no log do servidor qual ferramenta seria rejeitada, mas envia o esquema da ferramenta para a API mesmo assim. A API rejeita uma solicitação que inclua esse esquema com um erro 400 nomeando a ferramenta por sua posição. 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.

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 permissão 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
  }
}

A anotação anthropic/requiresUserInteraction requer Claude Code v2.1.199 ou posterior. Versões anteriores a ignoram e aplicam o fluxo de permissão padrão.

Algumas superfícies, como Remote Control e aplicações construídas no Agent SDK, normalmente permitem que você aprove chamadas de ferramentas 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 Remote Control. Requer Claude Code v2.1.214 ou posterior.

Responder a solicitações de elicitação MCP

Os servidores MCP podem solicitar entrada estruturada de você durante uma tarefa usando elicitação. Quando um servidor precisa de informações que não consegue obter por conta própria, Claude Code exibe um diálogo interativo e passa sua resposta de volta para o servidor. Nenhuma configuração é necessária do seu lado: diálogos de elicitação aparecem automaticamente quando um servidor os solicita.

Os servidores podem solicitar entrada de duas maneiras:

• Modo de formulário: Claude Code mostra um diálogo com campos de formulário definidos pelo servidor (por exemplo, um prompt de nome de usuário e senha). Preencha os campos e envie.
• Modo de URL: Claude Code abre uma URL do navegador para autenticação ou aprovação. Conclua o fluxo no navegador e confirme na CLI.

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.

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

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

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

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

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.

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 trunca cada descrição de ferramenta e instruções de cada servidor em 2.048 caracteres por padrão. Mantenha-as concisas e coloque detalhes críticos perto do início.

Para alterar o limite para cada servidor MCP em sua sessão, defina CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH como um número de caracteres. Esta variável requer Claude Code v2.1.280 ou posterior.

Configurar busca de ferramentas

A busca de ferramentas é ativada por padrão: as ferramentas MCP são adiadas e descobertas sob demanda. Claude Code a desativa quando ANTHROPIC_BASE_URL aponta para um host que não é de primeira parte, pois a maioria dos proxies não encaminha blocos tool_reference. Defina ENABLE_TOOL_SEARCH explicitamente para substituir esse fallback.

Definir CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS mantém a busca de ferramentas desativada. Você não pode substituí-la definindo ENABLE_TOOL_SEARCH você mesmo. Sua organização pode manter a busca de ferramentas ativada através de configurações gerenciadas, no Claude Code v2.1.227 ou posterior. Desativar capacidades de pré-lançamento cobre onde a substituição se aplica e o que a variável remove.

A busca de ferramentas requer um modelo que suporte blocos tool_reference: Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.5 e modelos posteriores. Consulte compatibilidade de modelo na documentação da API para a lista atual.

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 substitui isso.

Antes da v2.1.221, Claude Code desativava a busca de ferramentas para todos os modelos na Agent Platform do Google Cloud, a menos que você definisse ENABLE_TOOL_SEARCH=true.

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"]
  }
}

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. Cada ferramenta desse servidor é então carregada no contexto no início da sessão, independentemente da configuração ENABLE_TOOL_SEARCH. Use isso para um pequeno número de ferramentas que Claude precisa a cada turno, 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. Um servidor MCP também pode marcar ferramentas individuais como sempre carregadas incluindo "anthropic/alwaysLoad": true no objeto _meta da ferramenta, que tem o mesmo efeito apenas para essa ferramenta.

Definir alwaysLoad: true também faz a inicialização aguardar as ferramentas do servidor, limitado ao tempo limite 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.

Use MCP prompts as commands

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

Execute MCP prompts

/mcp__github__list_prs

/mcp__github__pr_review 456

/mcp__jira__create_issue login-bug high

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.