SpyBara
Go Premium

mcp.md 2026-05-02 18:14 UTC to 2026-05-04 22:58 UTC

1451 added, 0 removed.

2026
Sun 31 06:39 Sat 30 06:23 Fri 29 06:38 Thu 28 06:37 Wed 27 06:42 Tue 26 06:33 Sun 24 06:25 Sat 23 06:18 Fri 22 06:33 Thu 21 06:36 Wed 20 06:35 Tue 19 06:34 Mon 18 23:59 Sun 17 01:01 Fri 15 22:58 Thu 14 17:02 Wed 13 23:01 Tue 12 22:57 Mon 11 23:00 Sun 10 23:03 Sat 9 04:57 Fri 8 22:00 Thu 7 22:59 Tue 5 23:00 Mon 4 22:58 Sat 2 18:14 Fri 1 18:19

Conectar Claude Code a ferramentas via MCP

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

export const MCPServersTable = ({platform = "all"}) => { const ifYouAreAnAiAgentReadingThisYouShouldInsteadFetch = 'https://api.anthropic.com/mcp-registry/docs'; const [servers, setServers] = useState([]); const [loading, setLoading] = useState(true); const [error, setError] = useState(null); useEffect(() => { const fetchServers = async () => { try { setLoading(true); const allServers = []; let cursor = null; do { const url = new URL('https://api.anthropic.com/mcp-registry/v0/servers'); url.searchParams.set('version', 'latest'); url.searchParams.set('visibility', 'commercial'); url.searchParams.set('limit', '100'); if (cursor) { url.searchParams.set('cursor', cursor); } const response = await fetch(url); if (!response.ok) { throw new Error(Failed to fetch MCP registry: ${response.status}); } const data = await response.json(); allServers.push(...data.servers); cursor = data.metadata?.nextCursor || null; } while (cursor); const transformedServers = allServers.map(item => { const server = item.server; const meta = item._meta?.['com.anthropic.api/mcp-registry'] || ({}); const worksWith = meta.worksWith || []; const availability = { claudeCode: worksWith.includes('claude-code'), mcpConnector: worksWith.includes('claude-api'), claudeDesktop: worksWith.includes('claude-desktop') }; const remotes = server.remotes || []; const httpRemote = remotes.find(r => r.type === 'streamable-http'); const sseRemote = remotes.find(r => r.type === 'sse'); const preferredRemote = httpRemote || sseRemote; const remoteUrl = preferredRemote?.url || meta.url; const remoteType = preferredRemote?.type; const isTemplatedUrl = remoteUrl?.includes('{'); let setupUrl; if (isTemplatedUrl && meta.requiredFields) { const urlField = meta.requiredFields.find(f => f.field === 'url'); setupUrl = urlField?.sourceUrl || meta.documentation; } const urls = {}; if (!isTemplatedUrl) { if (remoteType === 'streamable-http') { urls.http = remoteUrl; } else if (remoteType === 'sse') { urls.sse = remoteUrl; } } let envVars = []; if (server.packages && server.packages.length > 0) { const npmPackage = server.packages.find(p => p.registryType === 'npm'); if (npmPackage) { urls.stdio = npx -y ${npmPackage.identifier}; if (npmPackage.environmentVariables) { envVars = npmPackage.environmentVariables; } } } return { name: meta.displayName || server.title || server.name, description: meta.oneLiner || server.description, documentation: meta.documentation, urls: urls, envVars: envVars, availability: availability, customCommands: meta.claudeCodeCopyText ? { claudeCode: meta.claudeCodeCopyText } : undefined, setupUrl: setupUrl }; }); setServers(transformedServers); setError(null); } catch (err) { setError(err.message); console.error('Error fetching MCP registry:', err); } finally { setLoading(false); } }; fetchServers(); }, []); const generateClaudeCodeCommand = server => { if (server.customCommands && server.customCommands.claudeCode) { return server.customCommands.claudeCode.replace('--transport streamable-http', '--transport http'); } const serverSlug = server.name.toLowerCase().replace(/[^a-z0-9]/g, '-'); if (server.urls.http) { return claude mcp add ${serverSlug} --transport http ${server.urls.http}; } if (server.urls.sse) { return claude mcp add ${serverSlug} --transport sse ${server.urls.sse}; } if (server.urls.stdio) { const envFlags = server.envVars && server.envVars.length > 0 ? server.envVars.map(v => --env ${v.name}=YOUR_${v.name}).join(' ') : ''; const baseCommand = claude mcp add ${serverSlug} --transport stdio; return envFlags ? ${baseCommand} ${envFlags} -- ${server.urls.stdio} : ${baseCommand} -- ${server.urls.stdio}; } return null; }; if (loading) { return

Loading MCP servers...
; } if (error) { return
Error loading MCP servers: {error}
; } const filteredServers = servers.filter(server => { if (platform === "claudeCode") { return server.availability.claudeCode; } else if (platform === "mcpConnector") { return server.availability.mcpConnector; } else if (platform === "claudeDesktop") { return server.availability.claudeDesktop; } else if (platform === "all") { return true; } else { throw new Error(Unknown platform: ${platform}); } }); return <> 

  <div className="cards-container">
    {filteredServers.map(server => {
const claudeCodeCommand = generateClaudeCodeCommand(server);
const mcpUrl = server.urls.http || server.urls.sse;
const commandToShow = platform === "claudeCode" ? claudeCodeCommand : mcpUrl;
return <div key={server.name} className="server-card">
          <div>
            {server.documentation ? <a href={server.documentation}>
                <strong>{server.name}</strong>
              </a> : <strong>{server.name}</strong>}
          </div>

          <p style={{
  margin: '0.5rem 0',
  fontSize: '0.9rem'
}}>
            {server.description}
          </p>

          {server.setupUrl && <p style={{
  margin: '0.25rem 0',
  fontSize: '0.8rem',
  fontStyle: 'italic',
  opacity: 0.7
}}>
              Requires user-specific URL.{' '}
              <a href={server.setupUrl} style={{
  textDecoration: 'underline'
}}>
                Get your URL here
              </a>.
            </p>}

          {commandToShow && !server.setupUrl && <>
            <p style={{
  display: 'block',
  fontSize: '0.75rem',
  fontWeight: 500,
  minWidth: 'fit-content',
  marginTop: '0.5rem',
  marginBottom: 0
}}>
              {platform === "claudeCode" ? "Command" : "URL"}
            </p>
            <div className="command-row">
              <code>
                {commandToShow}
              </code>
            </div>
          </>}
        </div>;

})}

</>; };

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.

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.

Servidores MCP populares

Aqui estão alguns servidores MCP comumente usados que você pode conectar ao Claude Code:

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

# 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 [options] <name> -- <command> [args...]

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

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

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.

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.

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 ambiente: Use ${CLAUDE_PLUGIN_ROOT} para arquivos agrupados do plugin e ${CLAUDE_PLUGIN_DATA} para estado persistente que sobrevive a atualizações de plugins
  • 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 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 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 diferentes dependendo de suas necessidades:

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.

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

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

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

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 falhará ao analisar a configuração.

Exemplos práticos

{/* ### Exemplo: Automatizar testes de navegador com Playwright

claude mcp add --transport stdio playwright -- npx -y @playwright/mcp@latest

Então escreva e execute testes de navegador:

Teste se o fluxo de login funciona com test@example.com

Tire uma captura de tela da página de checkout em mobile

Verifique se o recurso de pesquisa retorna resultados
``` */}

### Exemplo: Monitorar erros com Sentry

```bash theme={null}
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.

1

Adicione 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

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

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.

1

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.

2

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.

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
3

Autentique no Claude Code

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

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://. authServerMetadataUrl requer Claude Code v2.1.64 ou posterior. 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.

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

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

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

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

Adicionar servidores MCP de configuração JSON

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

1

Adicione um servidor MCP de JSON

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

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

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

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

Verifique se o servidor foi adicionado

claude mcp get weather-api

Importar servidores MCP do Claude Desktop

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

1

Importe servidores do Claude Desktop

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

Selecione quais servidores importar

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

3

Verifique se os servidores foram importados

claude mcp list

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 estão automaticamente disponíveis no Claude Code:

1

Configure servidores MCP no Claude.ai

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

2

Autentique o servidor MCP

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

3

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.

Para desabilitar servidores MCP do claude.ai no Claude Code, defina a variável de ambiente ENABLE_CLAUDEAI_MCP_SERVERS como false:

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

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

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.

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

1

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.

2

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

Tool Search mantém o uso de contexto MCP baixo adiando definições de ferramentas até que Claude precise delas. Apenas nomes de ferramentas são carregados no início da sessão, então adicionar mais servidores MCP tem impacto mínimo na sua 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. Está desabilitado por padrão no Vertex AI, que não aceita o cabeçalho beta de pesquisa de ferramentas, e 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 ativar. Este recurso requer modelos que suportam blocos tool_reference: Sonnet 4 e posterior, ou Opus 4 e posterior. Os modelos Haiku não suportam pesquisa de ferramentas.

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 no Vertex AI ou quando ANTHROPIC_BASE_URL é um host que não é de primeira parte
true Todas as ferramentas MCP adiadas, incluindo no Vertex AI e para ANTHROPIC_BASE_URL que não é de primeira parte
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.

Usar prompts MCP como comandos

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

Executar prompts MCP

1

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.

2

Execute um prompt sem argumentos

/mcp__github__list_prs
3

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

Configuração MCP gerenciada

Para organizações que precisam de controle centralizado sobre servidores MCP, Claude Code suporta duas opções de configuração:

  1. Controle exclusivo com managed-mcp.json: Implante um conjunto fixo de servidores MCP que os usuários não podem modificar ou estender
  2. Controle baseado em política com listas de permissão/bloqueio: Permita que os usuários adicionem seus próprios servidores, mas restrinja quais são permitidos

Essas opções permitem que administradores de TI:

  • Controle quais servidores MCP os funcionários podem acessar: Implante um conjunto padronizado de servidores MCP aprovados em toda a organização
  • Evite servidores MCP não autorizados: Restrinja os usuários de adicionar servidores MCP não aprovados
  • Desabilite MCP completamente: Remova a funcionalidade MCP completamente se necessário

Opção 1: Controle exclusivo com managed-mcp.json

Quando você implanta um arquivo managed-mcp.json, ele assume controle exclusivo sobre todos os servidores MCP. Os usuários não podem adicionar, modificar ou usar nenhum servidor MCP além daqueles definidos neste arquivo. Esta é a abordagem mais simples para organizações que desejam controle completo.

Os administradores do sistema implantam o arquivo de configuração em um diretório em todo o sistema:

  • macOS: /Library/Application Support/ClaudeCode/managed-mcp.json
  • Linux e WSL: /etc/claude-code/managed-mcp.json
  • Windows: C:\Program Files\ClaudeCode\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"
      }
    }
  }
}

Opção 2: Controle baseado em política com listas de permissão e bloqueio

Em vez de assumir controle exclusivo, os administradores podem permitir que os usuários configurem seus próprios servidores MCP enquanto aplicam restrições sobre quais servidores são permitidos. Esta abordagem usa allowedMcpServers e deniedMcpServers no arquivo de configurações gerenciadas.

Opções de restrição

Cada entrada na lista de permissão ou bloqueio pode restringir servidores de três maneiras:

  1. Por nome do servidor (serverName): Corresponde ao nome configurado do servidor
  2. Por comando (serverCommand): Corresponde ao comando exato e argumentos usados para iniciar servidores stdio
  3. Por padrão de URL (serverUrl): Corresponde a URLs de servidor remoto com suporte a caracteres curinga

Importante: Cada entrada deve ter exatamente um de serverName, serverCommand ou serverUrl.

Exemplo de configuração

{
  "allowedMcpServers": [
    // Permitir por nome do servidor
    { "serverName": "github" },
    { "serverName": "sentry" },

    // Permitir por comando exato (para servidores stdio)
    { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem"] },
    { "serverCommand": ["python", "/usr/local/bin/approved-server.py"] },

    // Permitir por padrão de URL (para servidores remotos)
    { "serverUrl": "https://mcp.company.com/*" },
    { "serverUrl": "https://*.internal.corp/*" }
  ],
  "deniedMcpServers": [
    // Bloquear por nome do servidor
    { "serverName": "dangerous-server" },

    // Bloquear por comando exato (para servidores stdio)
    { "serverCommand": ["npx", "-y", "unapproved-package"] },

    // Bloquear por padrão de URL (para servidores remotos)
    { "serverUrl": "https://*.untrusted.com/*" }
  ]
}

Como funcionam as restrições baseadas em comando

Correspondência exata:

  • Os arrays de comando devem corresponder exatamente - tanto o comando quanto todos os argumentos na ordem correta
  • Exemplo: ["npx", "-y", "server"] NÃO corresponderá a ["npx", "server"] ou ["npx", "-y", "server", "--flag"]

Comportamento do servidor stdio:

  • Quando a lista de permissão contém qualquer entrada serverCommand, servidores stdio devem corresponder a um desses comandos
  • Os servidores stdio não podem passar apenas pelo nome quando restrições de comando estão presentes
  • Isso garante que os administradores possam aplicar quais comandos são permitidos executar

Comportamento do servidor não-stdio:

  • Servidores remotos (HTTP, SSE, WebSocket) usam correspondência baseada em URL quando entradas serverUrl existem na lista de permissão
  • Se nenhuma entrada de URL existir, servidores remotos voltam para correspondência baseada em nome
  • As restrições de comando não se aplicam a servidores remotos

Como funcionam as restrições baseadas em URL

Os padrões de URL suportam caracteres curinga usando * para corresponder a qualquer sequência de caracteres. Isso é útil para permitir domínios inteiros ou subdomínios.

Exemplos de caracteres curinga:

  • https://mcp.company.com/* - Permitir todos os caminhos em um domínio específico
  • https://*.example.com/* - Permitir qualquer subdomínio de example.com
  • http://localhost:*/* - Permitir qualquer porta em localhost

Comportamento do servidor remoto:

  • Quando a lista de permissão contém qualquer entrada serverUrl, servidores remotos devem corresponder a um desses padrões de URL
  • Os servidores remotos não podem passar apenas pelo nome quando restrições de URL estão presentes
  • Isso garante que os administradores possam aplicar quais endpoints remotos são permitidos
Exemplo: Lista de permissão apenas de URL 
{
"allowedMcpServers": [
{ "serverUrl": "https://mcp.company.com/*" },
{ "serverUrl": "https://*.internal.corp/*" }
]
}

Resultado:

  • Servidor HTTP em https://mcp.company.com/api: ✅ Permitido (corresponde ao padrão de URL)
  • Servidor HTTP em https://api.internal.corp/mcp: ✅ Permitido (corresponde ao subdomínio curinga)
  • Servidor HTTP em https://external.com/mcp: ❌ Bloqueado (não corresponde a nenhum padrão de URL)
  • Servidor stdio com qualquer comando: ❌ Bloqueado (nenhuma entrada de nome ou comando para corresponder)
Exemplo: Lista de permissão apenas de comando 
{
"allowedMcpServers": [
{ "serverCommand": ["npx", "-y", "approved-package"] }
]
}

Resultado:

  • Servidor stdio com ["npx", "-y", "approved-package"]: ✅ Permitido (corresponde ao comando)
  • Servidor stdio com ["node", "server.js"]: ❌ Bloqueado (não corresponde ao comando)
  • Servidor HTTP nomeado "my-api": ❌ Bloqueado (nenhuma entrada de nome para corresponder)
Exemplo: Lista de permissão mista de nome e comando 
{
"allowedMcpServers": [
{ "serverName": "github" },
{ "serverCommand": ["npx", "-y", "approved-package"] }
]
}

Resultado:

  • Servidor stdio nomeado "local-tool" com ["npx", "-y", "approved-package"]: ✅ Permitido (corresponde ao comando)
  • Servidor stdio nomeado "local-tool" com ["node", "server.js"]: ❌ Bloqueado (entradas de comando existem mas não correspondem)
  • Servidor stdio nomeado "github" com ["node", "server.js"]: ❌ Bloqueado (servidores stdio devem corresponder aos comandos quando entradas de comando existem)
  • Servidor HTTP nomeado "github": ✅ Permitido (corresponde ao nome)
  • Servidor HTTP nomeado "other-api": ❌ Bloqueado (nome não corresponde)
Exemplo: Lista de permissão apenas de nome 
{
"allowedMcpServers": [
{ "serverName": "github" },
{ "serverName": "internal-tool" }
]
}

Resultado:

  • Servidor stdio nomeado "github" com qualquer comando: ✅ Permitido (nenhuma restrição de comando)
  • Servidor stdio nomeado "internal-tool" com qualquer comando: ✅ Permitido (nenhuma restrição de comando)
  • Servidor HTTP nomeado "github": ✅ Permitido (corresponde ao nome)
  • Qualquer servidor nomeado "other": ❌ Bloqueado (nome não corresponde)

Comportamento da lista de permissão (allowedMcpServers)

  • undefined (padrão): Sem restrições - os usuários podem configurar qualquer servidor MCP
  • Array vazio []: Bloqueio completo - os usuários não podem configurar nenhum servidor MCP
  • Lista de entradas: Os usuários podem configurar apenas servidores que correspondem por nome, comando ou padrão de URL

Comportamento da lista de bloqueio (deniedMcpServers)

  • undefined (padrão): Nenhum servidor é bloqueado
  • Array vazio []: Nenhum servidor é bloqueado
  • Lista de entradas: Servidores especificados são explicitamente bloqueados em todos os escopos

Notas importantes

  • Opção 1 e Opção 2 podem ser combinadas: Se managed-mcp.json existir, ele tem controle exclusivo e os usuários não podem adicionar servidores. As listas de permissão/bloqueio ainda se aplicam aos servidores gerenciados em si.
  • A lista de bloqueio tem precedência absoluta: Se um servidor corresponder a uma entrada de lista de bloqueio (por nome, comando ou URL), será bloqueado mesmo que esteja na lista de permissão
  • As restrições baseadas em nome, comando e URL funcionam juntas: um servidor passa se corresponder a qualquer entrada de nome, entrada de comando ou padrão de URL (a menos que bloqueado pela lista de bloqueio)