Guia de campo do Claude Code em português

MCP no Claude Code: como instalar, conferir e usar um servidor

Um servidor MCP liga o Claude Code a um sistema de fora: um rastreador de tarefas, um banco de dados, um navegador (p. 89). Abaixo, o primeiro servidor sem conta nem chave, o servidor local pelo npx, os escopos, o .mcp.json que vai para o git sem levar a chave e as armadilhas.

O que é um servidor MCP

Um servidor MCP é um programa que oferece ferramentas ao Claude. O Model Context Protocol é um padrão aberto: o mesmo servidor atende o Claude Code, o app do Claude e outros clientes. Conectado, ele deixa o Claude ler e agir direto no sistema, em vez de trabalhar com o que você cola na conversa. A regra prática da documentação: conecte um servidor quando você se pega copiando dados de outra ferramenta para o chat (p. 90). Cada ferramenta chega ao Claude com o nome mcp__<servidor>__<ferramenta>, e é por esse nome que se escrevem as regras de permissão.

Dois transportes contam: HTTP, o recomendado para servidor remoto, que é só uma URL; e stdio, um programa que o Claude Code inicia na sua máquina (npx, python, .exe). SSE está obsoleto.

O primeiro servidor, sem conta nem chave

A documentação do Claude Code tem um servidor MCP público, bom para o primeiro teste porque não pede login. O comando é o mesmo no PowerShell, no Prompt de Comando e no bash (p. 90):

PowerShell

claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp
claude mcp list
# claude-code-docs: https://code.claude.com/docs/mcp (HTTP) - ✔ Connected
claude mcp get claude-code-docs      # escopo, estado, tipo, URL
claude mcp remove claude-code-docs   # apaga a entrada e o token

"Added" não é conectado: só diz que a configuração foi gravada. O estado real sai do claude mcp list, como ✔ Connected, ! Needs authentication ou ✘ Failed to connect. Na sessão, peça pelo nome, para a resposta vir do servidor e não de uma busca na web: "Use o servidor claude-code-docs para descobrir o que a variável MCP_TIMEOUT faz".

Servidor local: tudo depois do --

Sem --transport, o padrão é stdio, e tudo o que vem depois do -- é o comando que sobe o servidor, passado intacto (p. 91):

PowerShell (a crase continua a linha)

claude mcp add playwright -- npx -y @playwright/mcp@latest
claude mcp add --env AIRTABLE_API_KEY=SUA_CHAVE --transport stdio `
  airtable -- npx -y airtable-mcp-server

Os exemplos com npx pedem Node 18 ou mais novo. Na primeira conexão o npx baixa o pacote, e a lista pode mostrar ✘ Failed to connect até terminar; se a partida é lenta, aumente o prazo de 30 s com $env:MCP_TIMEOUT = "60000" antes de abrir o claude.

Escopos: quem enxerga o servidor

EscopoOnde ficaQuem vê
local (o padrão)~/.claude.json, na entrada deste projetoVocê, só neste projeto
project.mcp.json na raiz do repositórioTodos que clonam
user~/.claude.json, no topoVocê, em todos os projetos

Escolha com --scope. No Windows, ~/.claude.json é C:\Users\<você>\.claude.json (p. 91). Um .mcp.json que veio no clone pode iniciar processos na sua máquina, por isso a sessão interativa pede aprovação antes de usá-lo; no claude -p não há quem aprove, e ele carrega sem perguntar.

O .mcp.json vai para o git; a chave, não

.mcp.json, na raiz do repositório

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

${VAR} vira o valor da variável de ambiente de cada pessoa, e ${VAR:-padrão} usa o padrão quando ela não existe. Sem type, uma entrada com url é lida como stdio e pulada com aviso (p. 92).

Login, conectores e custo

Servidor remoto que pede login aparece como ! Needs authentication; o login pelo navegador sai do painel /mcp ou de claude mcp login <nome>. Se você entra com uma conta do claude.ai, os conectores que já autorizou lá aparecem sozinhos no /mcp; com chave de API, não (p. 93). Cada servidor conectado ocupa um pouco da janela em toda sessão, mas o tool search vem ligado: na abertura entram só os nomes das ferramentas, e a definição completa só quando o Claude a procura (p. 92). Servidor que você não usa ainda sobe processo: desligue no /mcp. E servidor que lê conteúdo de fora (páginas, e-mails) abre porta para prompt injection: conecte só o que você confia (p. 98).

Leia também