Adicionar servidores MCP ao Claude Code (claude mcp add, .mcp.json, escopos)

HTTP é o transporte recomendado para servidores remotos. Servidores stdio rodam como processos locais na sua máquina. No stdio, o separador -- divide as opções do próprio Claude (como --transport, --env e --scope) do comando que inicia o servidor. Tudo depois de -- vai para o servidor sem alterações.

# Remote HTTP server
claude mcp add --transport http notion https://mcp.notion.com/mcp

# HTTP server with a Bearer token header
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

# Local stdio server with an environment variable
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

• Defina variáveis de ambiente com -e ou --env, por exemplo -e KEY=value.
• Se o nome do servidor vier logo depois de --env, a CLI lê o nome como outro par e o rejeita. Coloque outra opção, como --transport stdio, entre --env e o nome.
• --transport e --header também aceitam as formas curtas -t e -H.
• SSE está descontinuado. Você ainda pode passar --transport sse para conectar a um servidor que só suporta SSE.
• Se você já tem uma configuração JSON para um servidor, adicione-a com claude mcp add-json NAME 'JSON'.

Use -s ou --scope para escolher um de três escopos. Local (o padrão) carrega só no projeto atual e fica em ~/.claude.json. Project fica em .mcp.json na raiz do projeto, então seu time o recebe pelo controle de versão. User também fica em ~/.claude.json, mas carrega em todos os seus projetos. Quando o mesmo nome de servidor é definido em mais de um escopo, local vence project, e project vence user.

claude mcp add --transport http shared-server --scope project https://example.com/mcp
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

O .mcp.json suporta expansão de ${VAR} e ${VAR:-default} em command, args, env, url e headers. Sempre defina type em uma entrada remota: uma entrada com url mas sem type é um erro de configuração, porque o Claude Code trata uma entrada sem type como servidor stdio.

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    },
    "local-weather": {
      "type": "stdio",
      "command": "/path/to/weather-cli",
      "args": ["--api-key", "${WEATHER_API_KEY}"],
      "env": { "CACHE_DIR": "/tmp" }
    }
  }
}

• O Claude Code pede que você aprove servidores com escopo de projeto do .mcp.json antes de usá-los. Redefina essas escolhas com claude mcp reset-project-choices.
• Se uma variável referenciada não estiver definida e não tiver padrão, o servidor ainda carrega com o texto literal ${VAR}, e claude mcp list mostra um aviso.

O Claude Code suporta OAuth 2.0 para servidores remotos. Depois de adicionar um servidor que exige login, rode /mcp dentro do Claude Code e conclua o login no navegador. Os tokens são armazenados com segurança e renovados automaticamente. Use Clear authentication no menu /mcp para revogar o acesso.

claude mcp list
claude mcp get notion
claude mcp remove notion
claude mcp login sentry
claude mcp logout sentry

Remover um servidor remoto também apaga os tokens OAuth que o Claude Code armazenou para ele. Para remover uma definição de um escopo, rode claude mcp remove NAME --scope SCOPE.

• MCP_TIMEOUT define o timeout de inicialização do servidor em milissegundos, por exemplo MCP_TIMEOUT=10000 claude.
• MCP_TOOL_TIMEOUT define o timeout de execução das ferramentas. Sobrescreva-o para um servidor com um campo timeout (milissegundos) na entrada desse servidor no .mcp.json.
• O Claude Code avisa quando a saída de uma ferramenta MCP passa de 10.000 tokens e a limita a 25.000 tokens por padrão. Aumente o limite com MAX_MCP_OUTPUT_TOKENS.

export MAX_MCP_OUTPUT_TOKENS=50000
MCP_TIMEOUT=10000 claude