Conectar Claude Code a ferramentas via MCP

​

O que você pode fazer com MCP

• 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

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

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

​

Instalando servidores MCP

​

Opção 1: Adicionar um servidor HTTP remoto

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

​

Opção 2: Adicionar um servidor SSE remoto

# 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

# 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

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

​

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

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

​

De uma URL

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

​

De um comando npx, uvx, ou binário

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

​

De um bloco JSON mcpServers

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

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

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

​

Gerenciando seus servidores

# 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

​

Status do 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.

​

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

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

​

Detalhe do status do servidor

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

​

Avisos de configuração

• 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

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

​

Desabilitar um servidor sem removê-lo

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

​

MCP client runtimes

• 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

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

​

Dynamic tool updates

​

Notification streams on the v2 runtime

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

​

Automatic reconnection

​

Mid-session drops of a remote server

• 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

• 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

​

How Claude learns that a server failed

• 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

​

Automatic backgrounding of long tool calls

• 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

​

Plugin-provided MCP servers

• 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

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

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

• 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

mcp__plugin_my-plugin_database-tools__query

​

Escopos de instalação de MCP

​

Escopo local

# 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

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

​

Escopo de projeto

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

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

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

​

Escopo de usuário

# 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

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

​

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

​

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

• 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

​

Variáveis de credencial que leem como vazias

• 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

​

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

• 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

​

Exemplos práticos

​

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

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

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"

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

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

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

/mcp

​

Autenticar a partir da linha de comando

claude mcp login sentry

claude mcp login sentry --no-browser

​

Usar uma porta de callback OAuth fixa

# 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

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

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

​

Restringir escopos OAuth

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

​

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

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

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

• 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

​

Onde o auxiliar é executado

​

Quais variáveis um auxiliar pode ler

• 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

​

Confiar em uma pasta antes de seu headersHelper ser executado

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

​

Adicionar servidores MCP de configuração 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

claude mcp get weather-api

​

Importar servidores MCP do Claude Desktop

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

claude mcp list 

​

Usar servidores MCP do claude.ai

/mcp

• 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

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

​

Como os conectores chegam ao Claude Code

• 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

• 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

{
  "disableClaudeAiConnectors": true
}

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

​

Use Claude Code as an MCP server

# Start Claude as a stdio MCP server
claude mcp serve

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

which claude

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

​

Limites de saída do MCP e avisos

• 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/.

export MAX_MCP_OUTPUT_TOKENS=50000
claude

​

Aumentar o limite para uma ferramenta específica

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

​

Imagens em resultados de ferramentas

​

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

• 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

​

Ferramentas com esquemas de entrada inválidos

• 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

​

Exigir aprovação para uma ferramenta específica

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

​

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

• Modo de formulário: Claude Code mostra um diálogo com campos de formulário definidos pelo servidor (por exemplo, um prompt de nome de usuário e senha). Preencha os campos e envie.
• Modo de URL: Claude Code pergunta se você deseja abrir um link no seu navegador e o abre quando você aceita. Os servidores usam este modo para um fluxo que é concluído fora do terminal, como entrada.

​

Usar recursos MCP

​

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

​

Para autores de servidores MCP

• Que categoria de tarefas suas ferramentas lidam
• Quando Claude deve procurar por suas ferramentas
• Capacidades principais que seu servidor fornece

​

Configurar busca de ferramentas

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

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

# Disable tool search entirely
ENABLE_TOOL_SEARCH=false claude

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

​

Isentar um servidor do adiamento

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

​

Use MCP prompts as commands

​

Execute MCP prompts

/mcp__github__list_prs

/mcp__github__pr_review 456

/mcp__jira__create_issue login-bug high

​

Configuração MCP gerenciada