Pular para o conteúdo principal
Claude Code pode se conectar a centenas de ferramentas e fontes de dados externas através do Model Context Protocol (MCP), um padrão 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.

​
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 e-mails de 10 usuários aleatórios que usaram o recurso ENG-4521, com base no nosso banco de dados Postgres.”
  • Integrar designs: “Atualize nosso modelo de e-mail 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.”

​
Servidores MCP populares

Aqui estão alguns servidores MCP comumente usados que você pode conectar ao Claude Code:
Use servidores MCP de terceiros por sua conta e risco - Anthropic não verificou a correção ou segurança de todos esses servidores. Certifique-se de confiar nos servidores MCP que está instalando. Tenha especial cuidado ao usar servidores MCP que possam buscar conteúdo não confiável, pois estes podem expô-lo ao risco de injeção de prompt.
Precisa de uma integração específica? Encontre centenas de servidores MCP no GitHub, ou crie o seu próprio usando o SDK MCP.

​
Instalando servidores MCP

Os servidores MCP podem ser configurados de três maneiras diferentes 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"

​
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. 
# Sintaxe básica
claude mcp add --transport stdio <name> <command> [args...]

# Exemplo real: Adicionar servidor Airtable
claude mcp add --transport stdio airtable --env AIRTABLE_API_KEY=YOUR_KEY \
  -- npx -y airtable-mcp-server
Entendendo o parâmetro ”—”: O -- (duplo travessão) separa os sinalizadores CLI do próprio Claude dos comandos e argumentos que são passados para o servidor MCP. Tudo antes de -- são opções para Claude (como --env, --scope), e tudo depois de -- é o comando real para executar o servidor MCP.Por exemplo:
  • claude mcp add --transport stdio myserver -- npx server → executa npx server
  • claude mcp add --transport stdio myserver --env KEY=value -- python server.py --port 8080 → executa python server.py --port 8080 com KEY=value no ambiente
Isso evita conflitos entre os sinalizadores do Claude e os sinalizadores do servidor.

​
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 de um servidor específico
claude mcp get github

# Remover um servidor
claude mcp remove github

# (dentro do Claude Code) Verificar status do servidor
/mcp
Dicas:
  • Use o sinalizador --scope para especificar onde a configuração é armazenada:
    • local (padrão): Disponível apenas para você no projeto atual (era chamado de project em versões mais antigas)
    • project: Compartilhado com todos no projeto via arquivo .mcp.json
    • user: Disponível para você em todos os projetos (era chamado de global em versões mais antigas)
  • Defina variáveis de ambiente com sinalizadores --env (por exemplo, --env KEY=value)
  • 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)
  • Claude Code exibirá um aviso quando a saída da ferramenta MCP exceder 10.000 tokens. Para aumentar este limite, defina a variável de ambiente MAX_MCP_OUTPUT_TOKENS (por exemplo, MAX_MCP_OUTPUT_TOKENS=50000)
  • Use /mcp para autenticar com servidores remotos que requerem autenticação OAuth 2.0
Usuários do Windows: No Windows nativo (não WSL), servidores MCP locais que usam npx requerem o wrapper cmd /c para garantir a execução adequada.
# Isso cria command="cmd" que o Windows pode executar
claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package
Sem o wrapper cmd /c, você encontrará erros “Connection closed” porque o Windows não pode executar npx diretamente. (Veja a nota acima para uma explicação do parâmetro --.)

​
Servidores MCP fornecidos por plugins

Plugins podem agrupar servidores MCP, fornecendo automaticamente ferramentas e integrações quando o plugin é ativado. 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 é ativado, seus servidores MCP iniciam automaticamente
  • As ferramentas MCP do plugin aparecem ao lado das 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: 
{
  "database-tools": {
    "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
    "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
    "env": {
      "DB_URL": "${DB_URL}"
    }
  }
}
Ou inline em plugin.json: 
{
  "name": "my-plugin",
  "mcpServers": {
    "plugin-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "8080"]
    }
  }
}
Recursos MCP de plugins:
  • Ciclo de vida automático: Os servidores iniciam quando o plugin é ativado, mas você deve reiniciar Claude Code para aplicar alterações do servidor MCP (ativação ou desativação)
  • Variáveis de ambiente: Use ${CLAUDE_PLUGIN_ROOT} para caminhos relativos ao plugin
  • 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 e HTTP (o suporte de transporte pode 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. 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 recebem as mesmas ferramentas quando o plugin é instalado
Veja a referência de componentes de plugins para detalhes sobre agrupamento de servidores MCP com plugins.

​
Escopos de instalação MCP

Os servidores MCP podem ser configurados em três níveis de escopo diferentes, cada um servindo propósitos distintos para gerenciar a acessibilidade e o compartilhamento de servidores. Entender esses escopos ajuda você a determinar a melhor maneira de configurar servidores para suas necessidades específicas.

​
Escopo local

Servidores com escopo local representam o nível de configuração padrão e são armazenados em suas configurações de usuário específicas do projeto. Esses servidores permanecem privados para você e são acessíveis apenas ao trabalhar dentro do diretório do projeto atual. Este escopo é ideal para servidores de desenvolvimento pessoal, configurações experimentais ou servidores contendo credenciais sensíveis que não devem ser compartilhadas. 
# 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

​
Escopo do 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 do usuário

Servidores com escopo de usuário 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

​
Escolhendo o escopo correto

Selecione seu escopo com base em:
  • Escopo local: Servidores pessoais, configurações experimentais ou credenciais sensíveis específicas de um projeto
  • Escopo do projeto: Servidores compartilhados pela equipe, ferramentas específicas do projeto ou serviços necessários para colaboração
  • Escopo do usuário: Utilitários pessoais necessários em múltiplos projetos, ferramentas de desenvolvimento ou serviços frequentemente usados

​
Hierarquia de escopo e precedência

As configurações do servidor MCP seguem uma hierarquia de precedência clara. Quando servidores com o mesmo nome existem em múltiplos escopos, o sistema resolve conflitos priorizando primeiro servidores com escopo local, seguidos por servidores com escopo de projeto e, finalmente, servidores com escopo de usuário. Este design garante que configurações pessoais possam substituir as compartilhadas quando necessário.

​
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 definido, caso contrário usa default
Locais de expansão: 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 falhará ao analisar a configuração.

​
Exemplos práticos

​
Exemplo: Monitorar erros com Sentry

# 1. Adicionar o servidor MCP do Sentry
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# 2. Use /mcp para autenticar com sua conta Sentry
> /mcp

# 3. Depurar problemas de produção
> "Quais são os erros mais comuns nas últimas 24 horas?"
> "Mostre-me o rastreamento de pilha para o ID de erro abc123"
> "Qual implantação introduziu esses novos erros?"

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

# 1. Adicionar o servidor MCP do GitHub
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# 2. No Claude Code, autentique se necessário
> /mcp
# Selecione "Authenticate" para GitHub

# 3. Agora você pode pedir ao Claude para trabalhar 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

# 1. Adicionar o servidor de banco de dados com sua string de conexão
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:[email protected]:5432/analytics"

# 2. Consultar 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 requerem autenticação. Claude Code suporta OAuth 2.0 para conexões seguras.
1

Adicionar o servidor que requer autenticação

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

Use o comando /mcp dentro do Claude Code

No Claude Code, use o comando:
> /mcp
Depois 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
  • A autenticação OAuth funciona com servidores HTTP

​
Adicionar servidores MCP de configuração JSON

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

Adicionar 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"}}'
2

Verificar 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:
1

Importar servidores do Claude Desktop

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

Selecionar quais servidores importar

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

Verificar se os servidores foram importados

claude mcp list
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 o sinalizador --scope user para adicionar servidores à sua configuração de usuário
  • Os servidores importados terão os mesmos nomes que no Claude Desktop
  • Se servidores com os mesmos nomes já existirem, eles receberão um sufixo numérico (por exemplo, server_1)

​
Usar Claude Code como um servidor MCP

Você pode usar o próprio Claude Code como um servidor MCP que outros aplicativos podem conectar: 
# Iniciar 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
Depois use o caminho completo em sua configuração:
{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "/full/path/to/claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}
Sem o caminho correto do executável, você encontrará erros como spawn claude ENOENT.
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.
  • Observe que este servidor MCP está simplesmente expondo 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
Para aumentar o limite para ferramentas que produzem grandes saídas: 
# Definir um limite mais alto para saídas de ferramentas MCP
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
Se você frequentemente encontrar avisos de saída com servidores MCP específicos, considere aumentar o limite ou configurar o servidor para paginar ou filtrar suas respostas.

​
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

1

Listar recursos disponíveis

Digite @ em seu prompt para ver recursos disponíveis de todos os servidores MCP conectados. Os recursos aparecem ao lado dos arquivos no menu de preenchimento automático.
2

Referenciar 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
3

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 de 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.)

​
Usar prompts MCP como comandos de barra

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

​
Executar prompts MCP

1

Descobrir 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.
2

Executar um prompt sem argumentos

> /mcp__github__list_prs
3

Executar 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 (espaços se tornam sublinhados)

​
Configuração MCP corporativa

Para organizações que precisam de controle centralizado sobre servidores MCP, Claude Code suporta configurações MCP gerenciadas pela empresa. Isso permite que administradores de TI:
  • Controlar quais servidores MCP os funcionários podem acessar: Implante um conjunto padronizado de servidores MCP aprovados em toda a organização
  • Prevenir servidores MCP não autorizados: Opcionalmente restrinja usuários de adicionar seus próprios servidores MCP
  • Desabilitar MCP completamente: Remova a funcionalidade MCP completamente se necessário

​
Configurando a configuração MCP corporativa

Administradores de sistema podem implantar um arquivo de configuração MCP corporativa ao lado do arquivo de configurações gerenciadas:
  • macOS: /Library/Application Support/ClaudeCode/managed-mcp.json
  • Windows: C:\ProgramData\ClaudeCode\managed-mcp.json
  • Linux: /etc/claude-code/managed-mcp.json
O arquivo managed-mcp.json usa o mesmo formato que um arquivo .mcp.json padrão: 
{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    },
    "company-internal": {
      "type": "stdio",
      "command": "/usr/local/bin/company-mcp-server",
      "args": ["--config", "/etc/company/mcp-config.json"],
      "env": {
        "COMPANY_API_URL": "https://internal.company.com"
      }
    }
  }
}

​
Restringindo servidores MCP com listas de permissão e listas de negação

Além de fornecer servidores gerenciados pela empresa, administradores podem controlar quais servidores MCP os usuários podem configurar usando allowedMcpServers e deniedMcpServers no arquivo managed-settings.json:
  • macOS: /Library/Application Support/ClaudeCode/managed-settings.json
  • Windows: C:\ProgramData\ClaudeCode\managed-settings.json
  • Linux: /etc/claude-code/managed-settings.json
{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverName": "sentry" },
    { "serverName": "company-internal" }
  ],
  "deniedMcpServers": [
    { "serverName": "filesystem" }
  ]
}
Comportamento da lista de permissão (allowedMcpServers):
  • undefined (padrão): Sem restrições - usuários podem configurar qualquer servidor MCP
  • Array vazio []: Bloqueio completo - usuários não podem configurar nenhum servidor MCP
  • Lista de nomes de servidores: Usuários podem configurar apenas os servidores especificados
Comportamento da lista de negação (deniedMcpServers):
  • undefined (padrão): Nenhum servidor é bloqueado
  • Array vazio []: Nenhum servidor é bloqueado
  • Lista de nomes de servidores: Servidores especificados são explicitamente bloqueados em todos os escopos
Notas importantes:
  • Essas restrições se aplicam a todos os escopos: usuário, projeto, local e até mesmo servidores corporativos de managed-mcp.json
  • A lista de negação tem precedência absoluta: Se um servidor aparecer em ambas as listas, ele será bloqueado
Precedência de configuração corporativa: A configuração MCP corporativa tem a precedência mais alta e não pode ser substituída por configurações de usuário, local ou projeto.