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.

​

Servidores MCP populares

​

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 --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

​

Gerenciando seus servidores

# 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

​

Enviar mensagens com canais

# Isso cria command="cmd" que o Windows pode executar
claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

​

Servidores MCP fornecidos por 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)

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

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

• 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

​

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

​

Escopo de projeto

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

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

​

Escopo de usuário

# Adicionar um servidor de usuário
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

​

Escolhendo o escopo correto

• Escopo local: Servidores pessoais, configurações experimentais ou credenciais sensíveis específicas de um projeto
• Escopo de projeto: Servidores compartilhados em equipe, ferramentas específicas do projeto ou serviços necessários para colaboração
• Escopo de 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

​

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

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

• 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

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

​

Exemplos práticos

​

Exemplo: Monitorar erros com Sentry

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

/mcp

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

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

/mcp

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:[email protected]: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

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

/mcp

​

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

​

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

​

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

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

​

Usar Claude Code como um servidor MCP

# Inicie Claude como um servidor MCP stdio
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 MCP e avisos

• 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

# Defina um limite mais alto para saídas de ferramentas MCP
export MAX_MCP_OUTPUT_TOKENS=50000
claude

• 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

​

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 abre uma URL do navegador para autenticação ou aprovação. Complete o fluxo no navegador, depois confirme no CLI.

​

Usar recursos MCP

​

Referenciar recursos MCP

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

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

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

​

Escalar com MCP Tool Search

​

Como funciona

1. As ferramentas MCP são adiadas em vez de carregadas no contexto antecipadamente
2. Claude usa uma ferramenta de pesquisa para descobrir ferramentas MCP relevantes quando necessário
3. Apenas as ferramentas que Claude realmente precisa são carregadas no contexto
4. As ferramentas MCP continuam funcionando exatamente como antes da sua perspectiva

​

Para autores de servidores MCP

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

​

Configurar pesquisa de ferramentas

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

# Desabilite a pesquisa de ferramentas completamente
ENABLE_TOOL_SEARCH=false claude

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

​

Usar prompts MCP como comandos

​

Executar prompts MCP

/mcp__github__list_prs

/mcp__github__pr_review 456

/mcp__jira__create_issue "Bug no fluxo de login" high

​

Configuração MCP gerenciada

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

• 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

• 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

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

​

Opções de restrição

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

​

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

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

• 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

• 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

• 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

• 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

{
  "allowedMcpServers": [
    { "serverUrl": "https://mcp.company.com/*" },
    { "serverUrl": "https://*.internal.corp/*" }
  ]
}

{
  "allowedMcpServers": [
    { "serverCommand": ["npx", "-y", "approved-package"] }
  ]
}

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverCommand": ["npx", "-y", "approved-package"] }
  ]
}

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverName": "internal-tool" }
  ]
}

​

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)