Como configurar MCP no Claude Code: claude mcp add, .mcp.json e escopos

Pra configurar MCP no Claude Code, use o claude mcp add no terminal. Servidor remoto: claude mcp add --transport http <nome> <url>. Servidor local: claude mcp add <nome> -- <comando>. Por padrão a configuração vai pro escopo local, gravado em ~/.claude.json e visível só pra você naquele projeto. Com --scope project ela vai pro .mcp.json e o time recebe pelo git; com --scope user o servidor aparece em todos os seus projetos. Confira com claude mcp list.

Testei todos os comandos deste guia no Claude Code 2.1.296, numa máquina Linux sem login, com dois servidores públicos: o DeepWiki (HTTP, sem autenticação) e o servidor de arquivos oficial @modelcontextprotocol/server-filesystem (stdio, via npx). As saídas abaixo são as que o terminal devolveu. O que depende de sessão logada, como o painel /mcp e o login OAuth, vem da documentação oficial de MCP do Claude Code.

Se você quer escrever o seu próprio servidor, o passo a passo está em como criar um servidor MCP em Python. Aqui o foco é configurar servidores que já existem.

Como adicionar um servidor MCP remoto (HTTP)?

Servidor remoto é uma URL. A documentação recomenda o transporte HTTP pra esse caso e marca o SSE como deprecated.

$ claude mcp add --transport http deepwiki https://mcp.deepwiki.com/mcp
Added HTTP MCP server deepwiki with URL: https://mcp.deepwiki.com/mcp to local config
File modified: /home/box/.claude.json [project: /tmp/mcp-lab]

$ claude mcp list
Checking MCP server health…

deepwiki: https://mcp.deepwiki.com/mcp (HTTP) - ✔ Connected

Se o servidor pede login, o claude mcp list mostra ! Needs authentication. Foi o que aconteceu com o servidor do Notion:

$ claude mcp add --transport http notion https://mcp.notion.com/mcp
Added HTTP MCP server notion with URL: https://mcp.notion.com/mcp to local config

$ claude mcp list
...
notion: https://mcp.notion.com/mcp (HTTP) - ! Needs authentication

Pra fazer o login, abra o Claude Code e rode /mcp, ou use claude mcp login <nome> direto do shell. Esses dois passos eu não testei, porque a máquina de teste não tinha navegador nem conta logada. Estão na seção de autenticação da documentação.

Servidor com token no header

Pra API que usa token fixo, passe --header. Repare na diferença entre as duas saídas:

$ claude mcp add --transport http secure-api https://mcp.deepwiki.com/mcp \
    --header "Authorization: Bearer token-de-teste"
Added HTTP MCP server secure-api with URL: https://mcp.deepwiki.com/mcp to local config
Headers: {
  "Authorization": "[REDACTED]"
}

$ claude mcp get secure-api
secure-api:
  Scope: Local config (private to you in this project)
  Status: ✔ Connected
  Type: http
  URL: https://mcp.deepwiki.com/mcp
  Headers:
    Authorization: Bearer token-de-teste

O add esconde o valor. O claude mcp get mostra o token em texto puro, e o ~/.claude.json também guarda ele assim. Não cole a saída do get em issue ou print sem olhar antes.

Como adicionar um servidor MCP local (stdio)?

Servidor local é um processo que o Claude Code sobe na sua máquina. O -- separa as opções do Claude Code do comando do servidor, e tudo depois dele vai intacto pro servidor.

$ claude mcp add --transport stdio fs -- npx -y @modelcontextprotocol/server-filesystem /tmp/mcp-lab
Added stdio MCP server fs with command: npx -y @modelcontextprotocol/server-filesystem /tmp/mcp-lab to local config

$ claude mcp list
...
fs: npx -y @modelcontextprotocol/server-filesystem /tmp/mcp-lab - ✔ Connected

Pra passar variável de ambiente, use --env (ou -e). A ordem importa. O --env aceita vários pares, então se o nome do servidor vem logo depois dele, o CLI lê o nome como mais um par:

$ claude mcp add --env API_KEY=abc123 api-env -- npx -y @modelcontextprotocol/server-filesystem /tmp/mcp-lab
Invalid environment variable format: api-env, environment variables should be added as: -e KEY1=value1 -e KEY2=value2

$ claude mcp add --env API_KEY=abc123 --transport stdio api-env -- npx -y @modelcontextprotocol/server-filesystem /tmp/mcp-lab
Added stdio MCP server api-env with command: npx -y @modelcontextprotocol/server-filesystem /tmp/mcp-lab to local config

Com --transport stdio no meio, funciona. A documentação descreve exatamente esse caso.

Qual a diferença entre os escopos local, project e user?

O escopo decide onde a configuração fica gravada e em quais projetos o servidor aparece. O padrão é local.

Testei os três. O claude mcp get diz o escopo de cada servidor:

$ claude mcp add --transport http deepwiki --scope user https://mcp.deepwiki.com/mcp
Added HTTP MCP server deepwiki with URL: https://mcp.deepwiki.com/mcp to user config

$ claude mcp get deepwiki
deepwiki:
  Scope: User config (available in all your projects)
  Status: ✔ Connected
  Type: http
  URL: https://mcp.deepwiki.com/mcp

To remove this server, run: claude mcp remove deepwiki -s user

O servidor user adicionado numa pasta apareceu no list de outra. Os servidores locais da primeira pasta, não. Numa pasta sem nada configurado, a resposta foi esta:

$ cd /tmp/outra-pasta && claude mcp list
No MCP servers configured. Use `claude mcp add` to add a server.

Pegadinha de nome: o escopo local do MCP fica em ~/.claude.json, na sua home. Ele não tem nada a ver com o .claude/settings.local.json do projeto. A própria documentação faz essa ressalva. E global não é escopo:

$ claude mcp add --transport http stripe --scope global https://mcp.stripe.com
Invalid scope: global. Must be one of: local, user, project, dynamic, enterprise, claudeai, managed, agent

Como usar o .mcp.json pra dividir servidores com o time?

O --scope project cria ou atualiza o .mcp.json na raiz do projeto:

$ claude mcp add --scope project --env ROOT_DIR=/tmp/mcp-lab --transport stdio files \
    -- npx -y @modelcontextprotocol/server-filesystem /tmp/mcp-lab
Added stdio MCP server files with command: npx -y @modelcontextprotocol/server-filesystem /tmp/mcp-lab to project config
File modified: /tmp/mcp-lab/.mcp.json

$ cat .mcp.json
{
  "mcpServers": {
    "files": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/tmp/mcp-lab"
      ],
      "env": {
        "ROOT_DIR": "/tmp/mcp-lab"
      }
    }
  }
}

Commite esse arquivo e quem clonar o repositório recebe os mesmos servidores. Por segurança, o Claude Code pede aprovação antes de usar um servidor do .mcp.json. Até lá, ele aparece assim:

$ claude mcp get deepwiki
deepwiki:
  Scope: Project config (shared via .mcp.json)
  Status: ⏸ Pending approval (run `claude` to approve)
  Type: http
  URL: https://mcp.deepwiki.com/mcp

To remove this server, run: claude mcp remove deepwiki -s project

Pra aprovar, rode claude na pasta e aceite. Pra zerar as escolhas, claude mcp reset-project-choices. Um repositório clonado não consegue se aprovar sozinho: um enableAllProjectMcpServers commitado em .claude/settings.json é ignorado enquanto você não marca a pasta como confiável.

Um aviso que vi na prática. Em claude -p, no Agent SDK e em sessões na nuvem não existe esse prompt, e a documentação diz que os servidores do .mcp.json carregam sem perguntar. No teste, o claude -p "/context" listou as ferramentas de dois servidores que o claude mcp list ainda mostrava como pendentes. Se você roda o Claude Code em CI, revise o .mcp.json como revisa código.

Como não commitar segredo no .mcp.json?

Use variável de ambiente. O .mcp.json aceita ${VAR} e ${VAR:-padrão} em command, args, env, url e headers:

{
  "mcpServers": {
    "deepwiki": {
      "type": "http",
      "url": "${DEEPWIKI_URL:-https://mcp.deepwiki.com/mcp}"
    },
    "interno": {
      "type": "http",
      "url": "https://mcp.deepwiki.com/mcp",
      "headers": { "Authorization": "Bearer ${INTERNAL_TOKEN}" }
    }
  }
}

Se a variável não existe e não tem padrão, o servidor carrega mesmo assim, com o texto ${VAR} literal, e o claude mcp list avisa:

$ claude mcp list
...
MCP config diagnostics ⚠

[Contains warnings] Project config (shared via .mcp.json)
Location: /tmp/mcp-lab/.mcp.json
 └ [Warning] [interno] mcpServers.interno: Missing environment variables: INTERNAL_TOKEN

Um detalhe de segurança da documentação: em url e headers de servidor remoto, variáveis com credenciais do próprio Claude Code ou do provedor de nuvem, como ANTHROPIC_API_KEY, chegam vazias de propósito. Isso impede que um .mcp.json de terceiros mande a sua chave pra outro servidor. Se precisar passar uma dessas, copie o valor pra uma variável com outro nome.

O que acontece se o mesmo nome existir em mais de um escopo?

Pela documentação, o Claude Code usa uma definição só, inteira, nesta ordem: local, project, user, depois servidores de plugins e conectores do claude.ai. Os campos não se misturam entre escopos. No teste, com deepwiki em local e em project, o get mostrou a versão local, e o remove sem escopo se recusou a escolher:

$ claude mcp remove deepwiki
MCP server "deepwiki" exists in multiple scopes:
  - Local config (private to you in this project) (/home/box/.claude.json [project: /tmp/mcp-lab])
  - Project config (shared via .mcp.json) (/tmp/mcp-lab/.mcp.json)

To remove from a specific scope, use:
  claude mcp remove deepwiki -s local
  claude mcp remove deepwiki -s project

Com deepwiki em user e outro deepwiki ainda pendente no .mcp.json, o get mostrou a versão user como conectada. A documentação não trata esse caso de forma explícita, então não conte com ele. Use nomes diferentes por escopo.

Como adicionar um servidor a partir de um JSON?

Se a documentação do servidor te dá um bloco JSON, use add-json. O campo type é obrigatório pra servidor remoto: sem ele, o Claude Code lê a entrada como stdio. Pelo CLI, o erro sai seco:

$ claude mcp add-json weather '{"type":"http","url":"https://mcp.deepwiki.com/mcp"}'
Added http MCP server weather to local config

$ claude mcp add-json broken '{"url":"https://mcp.deepwiki.com/mcp"}'
Invalid configuration: : Invalid input

Como listar, inspecionar e remover servidores MCP?

claude mcp list                        # todos os servidores, com status
claude mcp get deepwiki                # detalhes e escopo de um servidor
claude mcp remove deepwiki -s local    # remove de um escopo
claude mcp reset-project-choices       # zera as aprovações do .mcp.json

Os status que apareceram no claude mcp list durante o teste:

• ✔ Connected: o Claude Code conectou e checou o servidor.
• ! Needs authentication: o servidor pede OAuth. Rode /mcp ou claude mcp login <nome>.
• ⏸ Pending approval: servidor do .mcp.json que você ainda não aprovou. O Claude Code nem tenta conectar.

A documentação lista outros, como ✘ Failed to connect, com o detalhe do erro numa linha Issue: do get. Pra desligar um servidor sem apagar a configuração, use o painel /mcp dentro do Claude Code. A escolha fica gravada por projeto no ~/.claude.json.

Mais um erro real, esse por acaso: alguns nomes são reservados pros servidores internos do Claude Code.

$ claude mcp add --transport http workspace https://mcp.deepwiki.com/mcp
Cannot add MCP server "workspace": this name is reserved.

Quanto contexto um servidor MCP ocupa?

Pouco, no começo. Com o tool search, ligado por padrão nos modelos suportados, só os nomes das ferramentas e as instruções do servidor entram no contexto quando a sessão abre. As definições completas carregam quando o Claude usa a ferramenta. Medi com claude -p "/context" numa pasta vazia e depois com o DeepWiki adicionado:

As linhas (deferred) não entram no total. São números do Claude Code 2.1.296 nesta máquina e mudam com versão, modelo e servidor. Pra medir o seu e cortar o resto, veja como economizar tokens no Claude Code.

Perguntas frequentes

Leia também

• Claude Code é um harness, o guia principal de Claude Code
• Como criar um servidor MCP em Python, pra quando o servidor que você precisa não existe
• Como economizar tokens no Claude Code: /context, /compact, subagentes e cache
• Como configurar hooks no Claude Code
• Harness, RAG e context engineering

Precisa conectar agentes aos sistemas internos da sua empresa? Fale com a Capiva.