Conectar Claude Code a ferramentas via MCP

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.

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

Para criar seu próprio servidor, consulte o guia do servidor MCP para os fundamentos do protocolo e a documentação de construção de conectores Claude para autenticação, testes e envio ao Diretório. Você também pode fazer com que Claude crie um servidor para você com o plugin oficial mcp-server-dev.

Instale o plugin

Em uma sessão Claude Code, execute:

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

Se Claude Code relatar que o marketplace não foi encontrado, execute /plugin marketplace add anthropics/claude-plugins-official primeiro e depois tente novamente a instalação. Após a instalação, execute /reload-plugins para ativá-lo na sessão atual.

Execute a skill de construção

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

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

Instalando servidores MCP

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

Opção 1: Adicionar um servidor HTTP remoto

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

# 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 ignora 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.

Opção 2: Adicionar um servidor SSE remoto

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

# 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

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 durante a 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 referenciá-la via expansão ${VAR} em um .mcp.json com escopo de projeto ou usuário command ou args requer um padrão como ${CLAUDE_PROJECT_DIR:-.}. As configurações MCP fornecidas por plugins substituem ${CLAUDE_PROJECT_DIR} diretamente e não precisam do padrão.

# 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

Importante: Separar argumentos do servidor com --Para servidores stdio, o -- (travessão duplo) separa as próprias opções do Claude, como --transport, --env e --scope, do comando e argumentos que executam o servidor. Tudo após -- é passado para o servidor sem modificação.Por exemplo:

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

Sem --, Claude Code tentaria analisar as flags do servidor, como --port acima, como suas próprias opções.--env aceita múltiplos pares KEY=value. Se o nome do servidor vem diretamente após --env, a CLI lê o nome como outro par e o rejeita, portanto coloque pelo menos uma outra opção entre --env e o nome do servidor, como nos exemplos acima.

Opção 4: Adicionar um servidor WebSocket remoto

Servidores WebSocket mantêm uma conexão bidirecional persistente, o que é adequado para servidores MCP remotos que enviam eventos para Claude sem solicitação. Use HTTP em vez disso quando seu servidor apenas responde a solicitações, já que HTTP suporta OAuth e a flag 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. A flag claude mcp add --transport não aceita ws.

Gerenciando seus servidores

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

# Listar todos os servidores configurados
claude mcp list

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

# Remover um servidor
claude mcp remove github

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

Servidores com escopo de projeto de .mcp.json que estão aguardando sua aprovação aparecem em claude mcp list como ⏸ Pending approval. Execute claude interativamente para revisar e aprovar. claude mcp get <name> mostra servidores pendentes como ⏸ Pending approval e servidores rejeitados como ✗ Rejected. 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 estão verificados no repositório até que você confie no workspace executando claude nele e aceitando a caixa de diálogo de confiança do workspace. Um repositório clonado não pode aprovar seus próprios servidores: enableAllProjectMcpServers ou enabledMcpjsonServers confirmado no .claude/settings.json do projeto é ignorado em uma pasta não confiável, e o servidor permanece em ⏸ Pending approval em vez de estar conectado e verificado de saúde. As aprovações dessas fontes ainda se aplicam em uma pasta não confiável:

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

As aprovações em um .claude/settings.local.json não rastreado também se aplicam, mas apenas depois que você aceita uma caixa de diálogo de confiança para essa pasta ou um de seus diretórios pai: Claude Code 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, as aprovações do arquivo aguardam a caixa de diálogo de confiança a menos que a pasta seja seu diretório de configuração pessoal: seu diretório inicial, ou um diretório cujo .claude você definiu como CLAUDE_CONFIG_DIR. Antes da v2.1.207, um .claude/settings.local.json não rastreado aprovava servidores em uma pasta que você nunca tinha confiado. Uma entrada disabledMcpjsonServers em qualquer arquivo de configurações ainda rejeita o servidor. O painel /mcp mostra a contagem de ferramentas ao lado de cada servidor conectado e sinaliza servidores que anunciam a capacidade de ferramentas, mas não expõem nenhuma ferramenta. Um servidor remoto cuja configuração tem uma url vazia aparece 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, para que Claude Code não o relate como um erro ou um problema de configuração. A visualização de detalhes do servidor em /mcp lê No URL configured for this server; defina a url da entrada para se conectar. Antes da v2.1.208, Claude Code relatava uma url vazia como um problema de configuração com um prompt para reconectar. Se sua solicitação precisar de ferramentas de um servidor que ainda está se conectando em segundo plano, Claude aguarda esse servidor antes de continuar. Com pesquisa de ferramentas habilitada, que é o padrão, a espera acontece dentro da chamada ToolSearch. Em configurações sem pesquisa de ferramentas, como Plataforma de Agente do Google Cloud, um ANTHROPIC_BASE_URL personalizado, ou ENABLE_TOOL_SEARCH=false, Claude usa a ferramenta WaitForMcpServers em vez disso. Alguns nomes de servidor são reservados para os servidores integrados do Claude Code: workspace, claude-in-chrome, computer-use, Claude Preview e Claude Browser. Se sua configuração define um servidor com um nome reservado, Claude Code o ignora 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 nomeiam o servidor integrado que o painel de visualização do aplicativo 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.

Atualizações dinâmicas de ferramentas

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.

Reconexão automática

Se um servidor HTTP ou SSE se desconectar durante a sessão, Claude Code se reconecta automaticamente com backoff exponencial: até cinco tentativas, começando com um atraso de um segundo e dobrando a cada vez. O servidor aparece como pendente em /mcp enquanto a reconexão está em andamento. Após cinco tentativas falhadas, o servidor é marcado como falho e você pode tentar novamente manualmente de /mcp. Servidores Stdio são processos locais e não são reconectados automaticamente. O mesmo backoff se aplica quando um servidor HTTP ou SSE falha sua conexão inicial na inicialização. A partir da v2.1.121, Claude Code tenta novamente a conexão inicial até três vezes em erros transitórios, como uma resposta 5xx, uma conexão recusada ou um tempo limite, e então marca o servidor como falho se ainda não conseguir se conectar. Erros de autenticação e não encontrado não são retentados porque exigem uma mudança de configuração para serem resolvidos. Quando um servidor configurado falha ao se conectar, Claude Code diz ao Claude qual servidor falhou e seu erro de conexão, incluindo em resultados ToolSearch que não encontram nenhuma ferramenta correspondente, para que Claude relate a falha de conexão em sua resposta. Requer pesquisa de ferramentas, que está habilitada por padrão. Em configurações sem pesquisa de ferramentas, como um ANTHROPIC_BASE_URL personalizado, ENABLE_TOOL_SEARCH=false, ou um modelo que não suporta pesquisa de ferramentas, e no Amazon Bedrock, Plataforma de Agente do Google Cloud e Microsoft Foundry, Claude Code não relata falhas de conexão de servidor ao Claude. Antes da v2.1.205, Claude Code não passava erros de conexão ao Claude, e Claude poderia responder como se as ferramentas do servidor falho nunca tivessem sido configuradas. A partir da v2.1.191, as solicitações de descoberta de capacidade que são executadas após uma conexão bem-sucedida, como tools/list, prompts/list e resources/list, também tentam novamente erros de rede transitórios e erros de servidor até três vezes com backoff curto. Erros de autenticação, respostas 4xx e tempos limite de solicitação não são retentados.

Enviar mensagens com canais

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

Dicas:

Use a flag -s ou --scope para especificar onde a configuração é armazenada:
- local (padrão): Disponível apenas para você no projeto atual. Versões mais antigas chamavam este escopo de project
- project: Compartilhado com todos no projeto via arquivo .mcp.json
- user: Disponível para você em todos os projetos. Versões mais antigas chamavam este escopo de global
Defina variáveis de ambiente com flags -e ou --env (por exemplo, -e KEY=value)
As flags --transport e --header também aceitam formas curtas -t e -H
Configure o tempo limite de inicialização do servidor MCP usando a variável de ambiente MCP_TIMEOUT (por exemplo, MCP_TIMEOUT=10000 claude define um tempo limite de 10 segundos)
Defina um tempo limite de execução de ferramenta por servidor adicionando um campo timeout em milissegundos à entrada .mcp.json desse servidor, por exemplo "timeout": 600000 para dez minutos. Isso substitui a variável de ambiente MCP_TOOL_TIMEOUT apenas para esse servidor
Claude Code exibe um aviso quando a saída da ferramenta MCP excede 10.000 tokens e limita a saída a 25.000 tokens por padrão. Para aumentar o limite, defina a variável de ambiente MAX_MCP_OUTPUT_TOKENS (por exemplo, MAX_MCP_OUTPUT_TOKENS=50000); o limite de aviso é fixo. Veja Limites de saída MCP e avisos
Use /mcp para autenticar com servidores remotos que exigem autenticação OAuth 2.0

O timeout por servidor é um limite de tempo de parede rígido por chamada de ferramenta, e notificações de progresso do servidor não o estendem. Valores abaixo de 1000 são 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 também há um segundo temporizador por solicitação que cobre cada solicitação até o primeiro byte de resposta do servidor. Esse temporizador é de 60 segundos a menos que você defina o timeout por servidor ou MCP_TOOL_TIMEOUT; definir um para 60 segundos ou superior aumenta o temporizador por solicitação para esse valor, um valor inferior não o encurta, e o padrão de 28 horas de um MCP_TOOL_TIMEOUT não definido nunca o alimenta. Servidores Stdio e WebSocket não têm temporizador por solicitação. Antes da v2.1.162, valores abaixo de 1000 eram arredondados para um segundo. 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 pela janela de inatividade é abortada com um erro em vez de aguardar o limite de tempo de parede. 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 servidores em processo do SDK. 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.

Servidores MCP fornecidos por plugins

Plugins podem agrupar servidores MCP, fornecendo automaticamente ferramentas e integrações quando o plugin está habilitado. Os servidores MCP de plugins funcionam de forma idêntica aos servidores configurados pelo usuário. Como funcionam os servidores MCP de plugins:

Plugins definem servidores MCP em .mcp.json na raiz do plugin ou inline em plugin.json
Quando um plugin está habilitado, seus servidores MCP iniciam automaticamente
As ferramentas MCP do plugin aparecem junto com as ferramentas MCP configuradas manualmente
Os servidores de plugins são gerenciados através da instalação de plugins, não comandos /mcp

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 de MCP de plugin:

Ciclo de vida automático: Na inicialização da sessão, os servidores para plugins habilitados se conectam automaticamente. Se você habilitar ou desabilitar um plugin durante uma sessão, execute /reload-plugins para conectar ou desconectar seus servidores MCP
Variáveis 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 a variáveis de ambiente do usuário: Acesso às mesmas variáveis de ambiente que servidores configurados manualmente
Múltiplos tipos de transporte: Suporte para transportes stdio, SSE, HTTP e WebSocket, embora o suporte de transporte possa variar por servidor

Visualizando servidores MCP de plugins:

# Dentro do Claude Code, veja todos os servidores MCP incluindo os de plugins
/mcp

Os servidores de plugins aparecem na lista com indicadores mostrando que vêm de plugins. Nomes de ferramentas MCP de plugin: As ferramentas de um servidor MCP agrupado em um 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 chamado my-plugin, uma ferramenta query é chamável como:

mcp__plugin_my-plugin_database-tools__query

Use este nome completo ao referenciar a ferramenta em regras de permissão, na lista allowed-tools de uma skill, em um campo tools de um subagente, ou em um 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 um 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 em um campo server de um hook mcp_tool. Benefícios dos servidores MCP de plugins:

Distribuição agrupada: Ferramentas e servidores empacotados juntos
Configuração automática: Nenhuma configuração MCP manual necessária
Consistência da equipe: Todos obtêm as mesmas ferramentas quando o plugin está instalado

Veja a referência de componentes de plugins para detalhes sobre como agrupar 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 servidores no nível empresarial via configuração gerenciada.

Escopo	Carrega em	Compartilhado com equipe	Armazenado em
Local	Apenas projeto atual	Não	`~/.claude.json`
Projeto	Apenas projeto atual	Sim, via controle de versão	`.mcp.json` na raiz do projeto
Usuário	Todos os seus projetos	Não	`~/.claude.json`

Escopo local

O escopo local é o padrão. Um servidor com escopo local carrega apenas no projeto onde você o adicionou e permanece privado para você. Claude Code o armazena em ~/.claude.json sob o caminho desse projeto, então o mesmo servidor não aparecerá em seus outros projetos. Use o escopo local para servidores de desenvolvimento pessoal, configurações experimentais ou servidores com credenciais que você não deseja no controle de versão.

O termo “escopo local” para servidores MCP difere das configurações locais gerais. Os servidores MCP com escopo local são armazenados em ~/.claude.json (seu diretório inicial), enquanto as configurações locais gerais usam .claude/settings.local.json (no diretório do projeto). Veja Configurações para detalhes sobre localizações de arquivos de configuração.

# 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. Este arquivo é projetado para ser verificado no controle de versão, garantindo que todos os membros da equipe tenham acesso às mesmas ferramentas e serviços MCP. Quando você adiciona um servidor com escopo de projeto, Claude Code cria ou atualiza automaticamente este arquivo com a estrutura de configuração apropriada.

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

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

{
  "mcpServers": {
    "shared-server": {
      "command": "/path/to/server",
      "args": [],
      "env": {}
    }
  }
}

Por razões de segurança, Claude Code solicita aprovação antes de usar servidores com escopo de projeto de arquivos .mcp.json. Se você precisar redefinir essas escolhas de aprovação, use o comando claude mcp reset-project-choices.

Escopo de usuário

Servidores com escopo de usuário são armazenados em ~/.claude.json e fornecem acessibilidade entre projetos, tornando-os disponíveis em todos os projetos em sua máquina enquanto permanecem privados para sua conta de usuário. Este escopo funciona bem para servidores de utilitários pessoais, ferramentas de desenvolvimento ou serviços que você usa frequentemente em diferentes projetos.

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

Escopo local
Escopo de projeto
Escopo de usuário
Servidores fornecidos por plugins
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.

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

Se uma variável de ambiente necessária não estiver definida e não tiver um valor padrão, Claude Code deixa o texto literal ${VAR} no valor e relata um aviso de variável ausente para esse servidor. A configuração ainda é carregada, então defina a variável ou adicione um fallback :-default para que o servidor inicie com o valor que você pretende.

Exemplos práticos

Exemplo: Monitorar erros com Sentry

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

Autentique com sua conta Sentry:

/mcp

Então depure problemas de produção:

Quais são os erros mais comuns nas últimas 24 horas?

Mostre-me o rastreamento de pilha para o erro ID abc123

Qual implantação introduziu esses novos erros?

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"

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

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

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. 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. 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. A partir da v2.1.195, quando uma atualização de token falha porque o servidor rejeita o token de atualização armazenado, Claude Code imediatamente mostra um aviso apontando para /mcp. O menu do servidor conectado lá oferece Re-autenticar, para que você possa 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. A partir da v2.1.193, 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. 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.

Adicione o servidor que requer autenticação

Por exemplo:

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

Use o comando /mcp dentro do Claude Code

No Claude Code, use o comando:

/mcp

Então siga os passos no seu navegador para fazer login.

Dicas:

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

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

Registre um aplicativo OAuth com o servidor

Crie um aplicativo através do portal do desenvolvedor do servidor e anote seu ID do cliente e segredo do cliente.Muitos servidores também exigem um URI de redirecionamento. Se assim for, escolha uma porta e registre um URI de redirecionamento no formato http://localhost:PORT/callback. Use essa mesma porta com --callback-port na próxima etapa.

Adicione o servidor com suas credenciais

Escolha um dos seguintes métodos. A porta usada para --callback-port pode ser qualquer porta disponível. Ela apenas precisa corresponder ao URI de redirecionamento que você registrou na etapa anterior.

claude mcp add
claude mcp add-json
claude mcp add-json (apenas porta de callback)
CI / variável de ambiente

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

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

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

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

Use --callback-port sem um ID de cliente para fixar a porta enquanto usa registro dinâmico de cliente:

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

Defina o segredo via variável de ambiente para pular o prompt interativo:

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

Autentique no Claude Code

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

Dicas:

O segredo do cliente é armazenado com segurança no seu chaveiro do sistema (macOS) ou em um arquivo de credenciais, não na sua configuração
Se o servidor usar um cliente OAuth público sem segredo, use apenas --client-id sem --client-secret
--callback-port pode ser usado com ou sem --client-id
Essas flags se aplicam apenas aos transportes HTTP e SSE. Elas não têm efeito em servidores stdio
Use claude mcp get <name> para verificar se as credenciais OAuth estão configuradas para um servidor

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, Claude Code se autentica novamente com os mesmos escopos fixados. Amplie oauth.scopes quando uma ferramenta que você precisa requer um escopo fora do conjunto fixado.

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
O comando é executado em um shell com um tempo limite de 10 segundos, a partir do diretório de trabalho atual da sessão. Use um caminho absoluto ou um comando em PATH para o script
Cabeçalhos dinâmicos substituem qualquer headers estático com o mesmo nome

O auxiliar é executado novamente em cada conexão, no início da sessão e ao reconectar. Não há cache, então seu script é responsável por qualquer reutilização de token. A partir da v2.1.193, se uma chamada de ferramenta retorna 401 Unauthorized ou 403 Forbidden, Claude Code automaticamente executa novamente o auxiliar, 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. Claude Code define essas variáveis de ambiente ao executar o auxiliar:

Variável	Valor
`CLAUDE_CODE_MCP_SERVER_NAME`	o nome do servidor MCP
`CLAUDE_CODE_MCP_SERVER_URL`	a URL do servidor MCP
`CLAUDE_PLUGIN_ROOT`	o diretório raiz do plugin. Definido apenas quando um plugin fornece o servidor

Use essas para escrever um único script auxiliar que serve múltiplos servidores MCP. Para um servidor fornecido por plugin, o auxiliar também é executado com seu diretório de trabalho definido para a raiz do plugin, para que um caminho headersHelper relativo seja resolvido dentro do diretório do plugin em vez de contra o diretório de trabalho da sessão. Requer Claude Code v2.1.195 ou posterior. 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 seu próprio ambiente ou de um arquivo de configuração. Antes da v2.1.207, headersHelper substituía valores ${user_config.*}.

headersHelper executa comandos shell arbitrários. Quando definido no escopo de projeto ou local, ele só é executado após você aceitar o diálogo de confiança do espaço de trabalho.

Adicionar servidores MCP de configuração JSON

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

Adicione um servidor MCP de JSON

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

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

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

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

Verifique se o servidor foi adicionado

claude mcp get weather-api

Dicas:

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

Importar servidores MCP do Claude Desktop

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

Importe servidores do Claude Desktop

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

Selecione quais servidores importar

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

Verifique se os servidores foram importados

claude mcp list

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

Dicas:

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

Usar servidores MCP do claude.ai

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

Configure servidores MCP no claude.ai

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

Autentique o servidor MCP

Complete quaisquer etapas de autenticação necessárias no claude.ai.

Visualize e gerencie servidores no Claude Code

No Claude Code, use o comando:

/mcp

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

A partir da v2.1.161, 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 re-autenticação. Os conectores do claude.ai são buscados apenas quando seu método de autenticação ativo é sua assinatura do claude.ai. Eles não são carregados quando ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, apiKeyHelper, ou um provedor de terceiros como Amazon Bedrock ou Google Cloud’s Agent Platform está ativo, mesmo que você tenha executado /login anteriormente. Se /mcp não listar um conector que você adicionou, execute /status para confirmar qual método de autenticação está ativo, desdefina essa variável de ambiente ou remova a configuração apiKeyHelper, depois execute /login para selecionar sua conta do claude.ai. Um servidor que você adicionou no Claude Code tem precedência sobre um conector do claude.ai que aponta para a mesma URL. Quando isso acontece, /mcp lista o conector como oculto e mostra como remover a duplicata se você preferir usar o conector. 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. A partir da v2.1.162, autenticar um desses hosts em /mcp mostra uma mensagem direcionando você para conectá-lo em Configurações → Conectores no claude.ai. Uma vez conectado lá, o conector aparece no Claude Code automaticamente.

Controles da organização em ferramentas de conectores

Sua organização pode definir controles por ferramenta em conectores do claude.ai. O Claude Code lê essas configurações na inicialização e as aplica localmente. Execute /mcp para ver qual configuração se aplica a cada ferramenta em um conector.

Ferramenta definida como ask: O Claude Code solicita em 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 do Claude vê-la, então ela nunca aparece na lista de ferramentas.

Aplicar esses controles requer Claude Code v2.1.129 ou posterior. Versões anteriores ignoram as configurações e aplicam o fluxo de permissão padrão.

Desabilitar conectores do claude.ai

Para desabilitar servidores MCP do claude.ai no Claude Code, defina disableClaudeAiConnectors 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 por fora de conectores em nuvem, mas um false em nível de projeto não pode re-habilitar 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 individuais do claude.ai em vez de todos eles, adicione-os a deniedMcpServers por nome ou por padrão de URL. Por exemplo, uma entrada serverName de "claude.ai Slack" bloqueia o conector Slack. Para alternar um conector ligado ou desligado apenas para o projeto atual, use o painel /mcp.

Estas configurações do lado do cliente governam sessões locais do Claude Code. Em sessões do Claude Code na web, conectores do claude.ai são provisionados pelo host remoto e chegam como entradas explícitas --mcp-config, então disableClaudeAiConnectors não se aplica lá. URLs de conectores também são reescritas através do proxy de sessão, então um padrão serverUrl de deniedMcpServers direcionado à URL do fornecedor não corresponderá. Gerencie quais conectores uma sessão em nuvem pode usar a partir das configurações da sua organização no claude.ai.

Usar Claude Code como um servidor MCP

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

# Inicie Claude como um servidor MCP stdio
claude mcp serve

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": {}
    }
  }
}

Configurando o caminho do executável: O campo command deve referenciar o executável do Claude Code. Se o comando claude não estiver no PATH do seu sistema, você precisará especificar o caminho completo para o executável.Para encontrar o caminho completo:

which claude

Então use o caminho completo na sua configuração:

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

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

Dicas:

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

Limites de saída MCP e avisos

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

Limite de aviso de saída: Claude Code exibe um aviso quando qualquer saída de ferramenta MCP excede 10.000 tokens
Limite configurável: você pode ajustar o máximo de tokens de saída MCP permitidos usando a variável de ambiente MAX_MCP_OUTPUT_TOKENS
Limite padrão: o máximo padrão é 25.000 tokens
Escopo: a variável de ambiente se aplica a ferramentas que não declaram seu próprio limite. Ferramentas que definem anthropic/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

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

export MAX_MCP_OUTPUT_TOKENS=50000
claude

Isso é particularmente útil ao trabalhar com servidores MCP que:

Consultam grandes conjuntos de dados ou bancos de dados
Geram relatórios ou documentação detalhados
Processam arquivos de log extensos ou informações de depuração

Aumentar o limite para uma ferramenta específica

Se você está construindo um servidor MCP, você pode permitir que ferramentas individuais retornem resultados maiores do que o limite padrão de persistência em disco definindo _meta["anthropic/maxResultSizeChars"] na entrada da ferramenta em resposta tools/list. Claude Code aumenta o limite dessa ferramenta para o valor anotado, até um teto rígido de 500.000 caracteres. Isso é útil para ferramentas que retornam saídas inerentemente grandes mas necessárias, como esquemas de banco de dados ou árvores de arquivos completas. Sem a anotação, resultados que excedem o limite padrão são persistidos em disco e substituídos por uma referência de arquivo na conversa.

{
  "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, então os usuários não precisam aumentar a variável de ambiente para ferramentas que a declaram. Ferramentas que retornam dados de imagem ainda estão sujeitas ao limite de token.

Se você encontrar frequentemente avisos de saída com servidores MCP específicos que você não controla, considere aumentar o limite MAX_MCP_OUTPUT_TOKENS. Você também pode pedir ao autor do servidor para adicionar a anotação anthropic/maxResultSizeChars ou para paginar suas respostas. A anotação não tem efeito em ferramentas que retornam conteúdo de imagem; para essas, aumentar MAX_MCP_OUTPUT_TOKENS é a única opção.

Esquemas de entrada de ferramenta com um combinador de 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 modificação. A partir do Claude Code v2.1.195, ferramentas com um combinador de 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 à descrição da ferramenta que diz ao Claude quais grupos de parâmetros pertencem juntos:

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

Seu servidor recebe quaisquer argumentos que Claude escolheu, então 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 ativa a reescrita, como uma máquina offline, ele ignora essa ferramenta, registra o motivo no log do servidor e deixa as outras ferramentas do servidor disponíveis. Versões anteriores a v2.1.195 ignoram cada ferramenta cujo esquema de entrada tem um anyOf, oneOf, ou allOf de nível raiz.

Exigir aprovação para uma ferramenta específica

Se você está construindo um servidor MCP, você pode marcar uma ferramenta como exigindo aprovação explícita a cada chamada definindo _meta["anthropic/requiresUserInteraction"] como true na entrada da ferramenta em resposta tools/list. O valor deve ser o booleano JSON true; qualquer outro valor é ignorado. Claude Code mostra o prompt de permissão dessa ferramenta a cada chamada, mesmo em modos de permissão acceptEdits, auto e bypassPermissions permission modes, e não oferece uma opção “não pergunte 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 em vez disso. O prompt tem que alcançar uma pessoa. No modo não interativo com --permission-prompt-tool, um resultado allow da ferramenta de prompt para uma ferramenta sinalizada é 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 o host do SDK deve mostrá-las 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 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. Quando uma sessão está conectada ao Remote Control ou a um host SDK, Claude Code marca a solicitação de permissão como exigindo interação do usuário, para que o cliente mostre o prompt de permissão da ferramenta para você responder em vez de uma ação de aprovação com um toque.

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

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

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

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, veja a especificação de elicitação MCP para detalhes de protocolo e exemplos de esquema.

Usar recursos MCP

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

Referenciar recursos MCP

Liste recursos disponíveis

Digite @ no seu prompt para ver recursos disponíveis de todos os servidores MCP conectados. Os recursos aparecem junto com arquivos no menu de preenchimento automático.

Referencie um recurso específico

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

Você pode analisar @github:issue://123 e sugerir uma correção?

Por favor, revise a documentação da API em @docs:file://api/authentication

Múltiplas referências de recursos

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

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

Dicas:

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

Escalar com MCP Tool Search

Tool Search mantém o uso de contexto MCP baixo adiando definições de ferramentas até que Claude precise delas. Apenas nomes de ferramentas e instruções do servidor são carregados no início da sessão, então adicionar mais servidores MCP tem impacto mínimo na sua janela de contexto. 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.

Como funciona

Tool Search é ativado por padrão. As ferramentas MCP são adiadas em vez de carregadas no contexto antecipadamente, e Claude usa uma ferramenta de pesquisa para descobrir as relevantes quando uma tarefa precisa delas. Apenas as ferramentas que Claude realmente usa entram no contexto. Da sua perspectiva, as ferramentas MCP funcionam exatamente como antes. Se você preferir carregamento baseado em limite, defina ENABLE_TOOL_SEARCH=auto para carregar esquemas antecipadamente quando se encaixarem em 10% da janela de contexto e adiar apenas o excesso. Veja Configurar pesquisa de ferramentas para todas as opções.

Para autores de servidores MCP

Se você está construindo um servidor MCP, o campo de instruções do servidor se torna mais útil com Tool Search habilitado. As instruções do servidor ajudam Claude a entender quando pesquisar suas ferramentas, semelhante a como skills funcionam. Adicione instruções de servidor claras e descritivas que expliquem:

Que categoria de tarefas suas ferramentas lidam
Quando Claude deve pesquisar suas ferramentas
Capacidades principais do seu servidor

Claude Code trunca descrições de ferramentas e instruções de servidor em 2KB cada. Mantenha-as concisas para evitar truncamento, e coloque detalhes críticos perto do início.

Configurar pesquisa de ferramentas

Tool Search é ativado por padrão: as ferramentas MCP são adiadas e descobertas sob demanda. Claude Code desabilita-o por padrão na Plataforma de Agentes do Google Cloud. Também é desabilitado quando ANTHROPIC_BASE_URL aponta para um host que não é de primeira parte, já que a maioria dos proxies não encaminha blocos tool_reference. Defina ENABLE_TOOL_SEARCH explicitamente para substituir qualquer fallback. Definir CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS mantém tool search desativado, e ENABLE_TOOL_SEARCH não pode substituí-lo. A variável remove o cabeçalho beta que as definições de ferramentas defer_loading e blocos de conteúdo tool_reference exigem. Tool Search requer um modelo que suporte blocos tool_reference: Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.5 e modelos posteriores. Veja compatibilidade de modelo na documentação da API para a lista atual. Na Plataforma de Agentes do Google Cloud, tool search é suportado para Claude Sonnet 4.5 e posterior e Claude Opus 4.5 e posterior. Controle o comportamento da pesquisa de ferramentas com a variável de ambiente ENABLE_TOOL_SEARCH:

Valor	Comportamento
(não definido)	Todas as ferramentas MCP adiadas e carregadas sob demanda. Volta a carregar antecipadamente na Plataforma de Agentes do Google Cloud ou quando `ANTHROPIC_BASE_URL` é um host que não é de primeira parte
`true`	Todas as ferramentas MCP adiadas. Claude Code envia o cabeçalho beta mesmo na Plataforma de Agentes do Google Cloud e através de proxies. As solicitações falham em modelos da Plataforma de Agentes do Google Cloud anteriores a Sonnet 4.5 ou Opus 4.5, ou em proxies que não suportam blocos `tool_reference`
`auto`	Modo de limite: ferramentas carregam antecipadamente se se encaixarem em 10% da janela de contexto, adiadas caso contrário
`auto:N`	Modo de limite com uma porcentagem personalizada, onde `N` é 0-100. Por exemplo, `auto:5` para 5%
`false`	Todas as ferramentas MCP carregadas antecipadamente, sem adiamento

# Use um limite personalizado de 5%
ENABLE_TOOL_SEARCH=auto:5 claude

# Desabilite a pesquisa de ferramentas completamente
ENABLE_TOOL_SEARCH=false claude

Ou defina o valor no seu campo env de settings.json. Você também pode desabilitar a ferramenta ToolSearch especificamente:

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

Isentar um servidor de adiamento

Se as ferramentas de um servidor devem estar sempre visíveis para Claude sem uma etapa de pesquisa, defina alwaysLoad como true na configuração desse servidor. Cada ferramenta desse servidor então carrega no contexto no início da sessão independentemente da configuração ENABLE_TOOL_SEARCH. Use isso para um pequeno número de ferramentas que Claude precisa a cada turno, já que cada ferramenta antecipada consome contexto que estaria disponível para sua conversa. A seguinte entrada .mcp.json isenta um servidor HTTP enquanto deixa outros servidores adiados:

{
  "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 e requer Claude Code v2.1.121 ou posterior. Um servidor MCP também pode marcar ferramentas individuais como sempre carregadas incluindo "anthropic/alwaysLoad": true no objeto _meta da ferramenta, que tem o mesmo efeito apenas para essa ferramenta. Definir alwaysLoad: true também bloqueia a inicialização até que o servidor se conecte, limitado ao tempo limite de conexão padrão de 5 segundos. Isso se aplica mesmo que a inicialização MCP seja não bloqueante por padrão, já que as ferramentas devem estar presentes quando o primeiro prompt é construído. Outros servidores continuam a se conectar em segundo plano.

Usar prompts MCP como comandos

Os servidores MCP podem expor prompts que se tornam disponíveis como comandos no Claude Code.

Executar prompts MCP

Descubra prompts disponíveis

Digite / para ver todos os comandos disponíveis, incluindo aqueles de servidores MCP. Os prompts MCP aparecem com o formato /mcp__servername__promptname.

Execute um prompt sem argumentos

/mcp__github__list_prs

Execute um prompt com argumentos

Muitos prompts aceitam argumentos. Passe-os separados por espaço após o comando:

/mcp__github__pr_review 456

/mcp__jira__create_issue "Bug no fluxo de login" high

Dicas:

Os prompts MCP são descobertos dinamicamente de servidores conectados
Os argumentos são analisados com base nos parâmetros definidos do prompt
Os resultados do prompt são injetados diretamente na conversa
Os nomes do servidor e do prompt são normalizados, com espaços convertidos em sublinhados

Configuração MCP gerenciada

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

⌘I

​O que você pode fazer com MCP

​Encontre e crie servidores MCP

​Instalando servidores MCP

​Opção 1: Adicionar um servidor HTTP remoto

​Opção 2: Adicionar um servidor SSE remoto

​Opção 3: Adicionar um servidor stdio local

​Opção 4: Adicionar um servidor WebSocket remoto

​Gerenciando seus servidores

​Atualizações dinâmicas de ferramentas

​Reconexão automática

​Enviar mensagens com canais

​Servidores MCP fornecidos por plugins

​Escopos de instalação de MCP

​Escopo local

​Escopo de projeto

​Escopo de usuário

​Hierarquia de escopo e precedência

​Expansão de variáveis de ambiente em .mcp.json

​Exemplos práticos

​Exemplo: Monitorar erros com Sentry

​Exemplo: Conectar ao GitHub para revisões de código

​Exemplo: Consultar seu banco de dados PostgreSQL

​Autenticar com servidores MCP remotos

​Autenticar a partir da linha de comando

​Usar uma porta de callback OAuth fixa

​Usar credenciais OAuth pré-configuradas

​Substituir descoberta de metadados OAuth

​Restringir escopos OAuth

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

​Adicionar servidores MCP de configuração JSON

​Importar servidores MCP do Claude Desktop

​Usar servidores MCP do claude.ai

​Controles da organização em ferramentas de conectores

​Desabilitar conectores do claude.ai

​Usar Claude Code como um servidor MCP

​Limites de saída MCP e avisos

​Aumentar o limite para uma ferramenta específica

​Esquemas de entrada de ferramenta com um combinador de nível raiz

​Exigir aprovação para uma ferramenta específica

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

​Usar recursos MCP

​Referenciar recursos MCP

​Escalar com MCP Tool Search

​Como funciona

​Para autores de servidores MCP

​Configurar pesquisa de ferramentas

​Isentar um servidor de adiamento

​Usar prompts MCP como comandos

​Executar prompts MCP

​Configuração MCP gerenciada

O que você pode fazer com MCP

Encontre e crie servidores MCP

Instalando servidores MCP

Opção 1: Adicionar um servidor HTTP remoto

Opção 2: Adicionar um servidor SSE remoto

Opção 3: Adicionar um servidor stdio local

Opção 4: Adicionar um servidor WebSocket remoto

Gerenciando seus servidores

Atualizações dinâmicas de ferramentas

Reconexão automática

Enviar mensagens com canais

Servidores MCP fornecidos por plugins

Escopos de instalação de MCP

Escopo local

Escopo de projeto

Escopo de usuário

Hierarquia de escopo e precedência

Expansão de variáveis de ambiente em `.mcp.json`

Exemplos práticos

Exemplo: Monitorar erros com Sentry

Exemplo: Conectar ao GitHub para revisões de código

Exemplo: Consultar seu banco de dados PostgreSQL

Autenticar com servidores MCP remotos

Autenticar a partir da linha de comando

Usar uma porta de callback OAuth fixa

Usar credenciais OAuth pré-configuradas

Substituir descoberta de metadados OAuth

Restringir escopos OAuth

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

Adicionar servidores MCP de configuração JSON

Importar servidores MCP do Claude Desktop

Usar servidores MCP do claude.ai

Controles da organização em ferramentas de conectores

Desabilitar conectores do claude.ai

Usar Claude Code como um servidor MCP

Limites de saída MCP e avisos

Aumentar o limite para uma ferramenta específica

Esquemas de entrada de ferramenta com um combinador de nível raiz

Exigir aprovação para uma ferramenta específica

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

Usar recursos MCP

Referenciar recursos MCP

Escalar com MCP Tool Search

Como funciona

Para autores de servidores MCP

Configurar pesquisa de ferramentas

Isentar um servidor de adiamento

Usar prompts MCP como comandos

Executar prompts MCP

Configuração MCP gerenciada