MCP no Claude Code: conexão de servidores, escopos, MCP remoto e exemplos reais

Como adicionar um servidor

# local server over stdio (runs the command, talks over its stdin/stdout)
claude mcp add playwright -- npx @playwright/mcp@latest

# remote server over HTTP
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# with a header (API-key style auth)
claude mcp add --transport http posthog https://mcp.posthog.com/mcp \
  --header "Authorization: Bearer $POSTHOG_API_KEY"

claude mcp list      # what is configured
claude mcp remove playwright

Servidores stdio são programas que o Claude Code inicia para você — a maioria dos servidores da comunidade são pacotes npm ou Python executados dessa forma. Servidores remotos são URLs; eles se autenticam com OAuth (execute /mcp em uma sessão e siga o fluxo no navegador) ou com um cabeçalho que você informa ao adicionar o servidor, como no exemplo do PostHog. Consulte a documentação de cada fornecedor para obter a URL atual — os endpoints remotos mudam.

Escopos e .mcp.json

• local (padrão) — armazenado nas suas configurações de usuário, apenas para este projeto. Servidores pessoais e privados.
• project (--scope project) — gravado em .mcp.json na raiz do repositório e compartilhado com todos que o clonam. O Claude Code pede confirmação antes de confiar nos servidores de um projeto pela primeira vez.
• user (--scope user) — disponível em todos os projetos na sua máquina.

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "${DATABASE_URL}"]
    }
  }
}

.mcp.json oferece suporte à expansão de variáveis de ambiente, de modo que o repositório pode incluir a definição do servidor enquanto cada desenvolvedor fornece suas próprias credenciais.

Como usar um servidor em uma sessão

Após a conexão, as ferramentas do servidor ficam disponíveis — peça "os erros das últimas 24 horas no PostHog" e o Claude Code chama a ferramenta. Os recursos disponibilizados pelo servidor podem ser referenciados com menções com @ (@github:issue://123), que os incluem no contexto sob demanda. Os prompts definidos por um servidor aparecem como comandos de barra em /mcp__<server>__<prompt>. /mcp mostra o status da conexão, permite reconectar ou autenticar e lista todas as ferramentas com suas descrições.

Exemplos que vale a pena copiar

• PostHog MCP — análises de produto de dentro do agente: "qual feature flag controla este código e como está sua implantação gradual?" O PostHog publica um servidor MCP remoto; adicione-o com --transport http e sua chave de API pessoal como cabeçalho bearer.
• GitHub — issues e pull requests como contexto; combine com a Action do guia do GitHub para o ciclo de revisão.
• Playwright — um navegador real para testes de ponta a ponta e para verificar a interface que você acabou de alterar; consulte o guia de automação de QA.
• Postgres / SQLite — consultas e migrações que levam o esquema em conta; forneça um usuário com acesso somente de leitura, a menos que pretenda permitir alterações.
• Sistema de arquivos fora do repositório — --add-dir é mais simples para diretórios adicionais; o MCP serve para elementos que não são arquivos.

Custo e contexto

Cada resultado de ferramenta retornado por um servidor MCP entra na conversa e é reenviado em cada turno seguinte. Um servidor que retorna 5,000 linhas é uma bomba de contexto. Prefira ferramentas com limites, peça resumos e /compact após uma consulta pesada. Os servidores são executados localmente ou se conectam ao fornecedor; eles não passam pelo endpoint do modelo, portanto ANTHROPIC_BASE_URL=https://aiprimetech.io não é afetado — apenas os tokens consumidos pelos resultados são cobrados.

export ANTHROPIC_BASE_URL=https://aiprimetech.io
export ANTHROPIC_API_KEY=your_key

Perguntas frequentes

A AI Prime Tech é um gateway de API independente e não é afiliada, endossada nem patrocinada pela Anthropic. “Claude” e “Claude Code” são marcas comerciais da Anthropic. Os recursos do Claude Code descritos aqui seguem a documentação pública da Anthropic no momento da redação e mudam com frequência; os preços e as listas de modelos nesta página são obtidos das configurações atuais deste gateway.