Como conectar um servidor MCP ao Claude Code com comandos, escopos e .mcp.json

Para conectar um servidor MCP ao Claude Code, basta um comando: claude mcp add. O MCP (Model Context Protocol) é o padrão aberto que deixa o assistente usar ferramentas e dados externos, como um sistema de tarefas, um banco de dados ou uma API. Este tutorial mostra os comandos oficiais para servidores remotos e locais, os escopos de configuração e o arquivo .mcp.json para compartilhar a configuração com a equipe.

Pré-requisitos

• Claude Code instalado.
• A URL do servidor remoto que você quer usar, ou o comando que inicia um servidor local. Os exemplos abaixo usam os da documentação oficial.
• Para servidores locais em Node, o npx disponível no terminal.

Passo 1: adicionar um servidor remoto (HTTP)

A documentação recomenda servidores remotos por HTTP. A sintaxe é:

claude mcp add --transport http <nome> <url>

O exemplo oficial conecta o Notion:

claude mcp add --transport http notion https://mcp.notion.com/mcp

Se o servidor exigir um token, passe o cabeçalho de autorização:

claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Não coloque tokens reais em comandos que ficam no histórico do terminal ou em arquivos versionados. A documentação mostra, mais abaixo, como usar variáveis de ambiente no .mcp.json.

O transporte SSE continua existindo (--transport sse), mas a documentação o marca como obsoleto.

Passo 2: adicionar um servidor local (stdio)

Servidores locais rodam como um processo na sua máquina. A sintaxe usa -- para separar as opções do Claude do comando do servidor:

claude mcp add [options] <nome> -- <comando> [args...]

O exemplo da documentação conecta o Airtable e passa a chave como variável de ambiente:

claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

Tudo que vem depois do -- é repassado ao servidor sem alteração.

Passo 3: adicionar a partir de JSON

Se você já tem a configuração em JSON, use add-json:

claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

Passo 4: escolher o escopo

O escopo define onde a configuração fica salva e quem a enxerga:

Escopo	Carrega em	Compartilhado com a equipe	Fica em
Local (padrão)	Só o projeto atual	Não	~/.claude.json
Projeto	Só o projeto atual	Sim, via controle de versão	.mcp.json na raiz
Usuário	Todos os seus projetos	Não	~/.claude.json

Use a opção --scope para escolher:

claude mcp add --transport http stripe --scope local https://mcp.stripe.com
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

Quando o mesmo servidor está definido em mais de um lugar, a precedência é: local, projeto, usuário, servidores de plugins e, por último, conectores do claude.ai. Os campos não são mesclados entre escopos.

Passo 5: compartilhar com a equipe pelo .mcp.json

No escopo de projeto, o Claude Code grava um arquivo .mcp.json na raiz. Ele pode ir para o Git. O formato é este:

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

O arquivo aceita expansão de variáveis de ambiente com ${VAR} e ${VAR:-padrão}. Assim, o segredo fica fora do repositório:

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

Servidores definidos em .mcp.json pedem aprovação interativa antes do primeiro uso. Para zerar essas escolhas:

claude mcp reset-project-choices

Passo 6: gerenciar e verificar

Os comandos de manutenção são:

# Listar todos os servidores configurados
claude mcp list

# Ver detalhes de um servidor
claude mcp get notion

# Remover um servidor
claude mcp remove notion

# Fazer login (OAuth) pelo terminal
claude mcp login <nome>

# Apagar credenciais salvas
claude mcp logout <nome>

Dentro do Claude Code, digite /mcp para ver o status das conexões.

Passo 7: cuidado com regras de permissão

As ferramentas de um servidor MCP aparecem para o Claude com o formato mcp__<servidor>__<ferramenta>. O changelog do Claude Code registra, na versão 2.1.299, de 14 de outubro de 2026, que uma regra mcp__a deixou de casar com um servidor chamado a__b, e manda usar mcp__<servidor>__* para liberar todas as ferramentas de um servidor. Se você tinha regras antigas no settings.json, revise.

Para servidores que vêm dentro de plugins, a documentação mostra o formato mcp__plugin_<plugin>_<servidor>__<ferramenta>. Um padrão escrito só com o nome do servidor nunca casa com servidores de plugins.

Resultado esperado

Depois do claude mcp add, o servidor aparece em claude mcp list e em /mcp. As ferramentas ficam disponíveis na conversa, e o Claude passa a usá-las quando o pedido combina com elas. Para servidores com OAuth, rode claude mcp login <nome> ou autentique pelo /mcp.

Erros comuns

• Esquecer o -- em servidores locais: sem ele, as opções do servidor se misturam com as do Claude.
• Servidor no escopo errado: se o servidor não aparece em outro projeto, ele foi salvo no escopo local. Use --scope user.
• Segredo no .mcp.json: use ${VAR} em vez de colocar o token no arquivo versionado.
• Servidor do .mcp.json não carrega: ele precisa de aprovação interativa. Se recusou sem querer, use claude mcp reset-project-choices.
• Regras de permissão que pararam de funcionar: troque o nome solto do servidor pelo padrão mcp__<servidor>__*.