# Configurar MCP no Claude Code: adicionar servidores

URL: https://agentvera.dev/pt/blog/claude-code-mcp-setup/ · Publicado: 2026-10-28

Como adicionar servidores MCP ao Claude Code: claude mcp add para stdio e HTTP, escopos, .mcp.json, /mcp e OAuth, importar do Claude Desktop, timeouts e limites.

**Resumo:**

- Você adiciona um servidor com claude mcp add: as opções vêm antes do nome, e o comando de um servidor stdio local vem depois de --. Servidores remotos usam --transport http com uma URL.
- O escopo decide onde ele fica salvo: local (padrão) e user em ~/.claude.json; project em um .mcp.json na raiz do repo, que você pode commitar.
- Com /mcp dentro de uma sessão você vê o status, faz login em servidores OAuth e desativa servidores. MCP_TIMEOUT e MAX_MCP_OUTPUT_TOKENS resolvem a maioria dos problemas de inicialização e de saída.
- O Claude Code pergunta antes de usar os servidores do .mcp.json de um projeto. Revise-os como qualquer código do repo e guarde tokens em referências ${VAR}, não no arquivo.

Para configurar MCP no Claude Code, rode `claude mcp add` no terminal. Um servidor local é `claude mcp add <nome> -- <comando>`, um remoto é `claude mcp add --transport http <nome> <url>`, e `--scope` decide se o servidor vale só para você neste projeto (`local`, o padrão), para o time inteiro por meio de um arquivo `.mcp.json` (`project`) ou para você em todos os projetos (`user`). Depois digite `/mcp` dentro de uma sessão para conferir a conexão e fazer login nos servidores que usam OAuth.

Este guia passa por cada etapa: transportes, o separador `--`, variáveis de ambiente e headers, escopos, escrever o `.mcp.json` à mão, os comandos `list`, `get` e `remove`, OAuth, importação do Claude Desktop, timeouts e limites de saída, e o que conferir antes de confiar nos servidores de um projeto. Os comandos vêm da [documentação de MCP do Claude Code](https://code.claude.com/docs/en/mcp "Documentação de MCP do Claude Code") da Anthropic, em outubro de 2026. Se MCP é novidade para você, comece por [o que é um servidor MCP](/pt/blog/what-is-mcp-server/ "O que é um servidor MCP"); se quer saber quais servidores adicionar, veja [os melhores servidores MCP para programar](/pt/blog/best-mcp-servers-for-coding/ "Os melhores servidores MCP para programar").

## Referência rápida

| Tarefa | Comando |
| --- | --- |
| Adicionar servidor local (stdio) | `claude mcp add <nome> -- <comando> [argumentos...]` |
| Adicionar servidor remoto (HTTP) | `claude mcp add --transport http <nome> <url>` |
| Adicionar a partir de um trecho JSON | `claude mcp add-json <nome> '<json>'` |
| Compartilhar com o time | adicione `--scope project` (grava o `.mcp.json`) |
| Usar em todos os seus projetos | adicione `--scope user` |
| Listar servidores e o status deles | `claude mcp list` |
| Ver os detalhes de um servidor | `claude mcp get <nome>` |
| Remover um servidor | `claude mcp remove <nome>` |
| Fazer login em um servidor OAuth | `/mcp` em uma sessão, ou `claude mcp login <nome>` |
| Importar do Claude Desktop | `claude mcp add-from-claude-desktop` |
| Status, login, desativar, reconectar | `/mcp` dentro do Claude Code |

As opções curtas também funcionam: `-t` para `--transport`, `-s` para `--scope`, `-e` para `--env` e `-H` para `--header`.

## Escolha o transporte: stdio, HTTP ou SSE

Um servidor [MCP](/pt/glossary/mcp/ "MCP") chega ao Claude Code de uma de três formas:

| Transporte | O que é | Quando usar |
| --- | --- | --- |
| `stdio` | Um processo local que o Claude Code inicia e com o qual conversa por stdin e stdout | Servidores que você roda com `npx`, `uvx`, Docker ou um script próprio |
| `http` | Um servidor remoto via HTTP streamable | Serviços hospedados: Notion, Sentry, GitHub, Stripe e outros. A Anthropic recomenda para servidores remotos |
| `sse` | Server-Sent Events | Só servidores remotos antigos. A documentação marca o SSE como obsoleto |

Você quase não precisa mais de `--transport sse`. Desde o Claude Code 2.1.265, `claude mcp add --transport http` tenta HTTP primeiro e muda sozinho para SSE quando o servidor não aceita HTTP. Em versões mais antigas, passe `--transport sse` explicitamente.

## Adicionar um servidor stdio local

A regra que mais confunde: as opções do próprio Claude Code (`--transport`, `--scope`, `--env`) vêm **antes** do nome do servidor, e tudo depois de `--` é o comando do servidor, repassado sem alteração.

```bash
# Forma básica
claude mcp add [opções] <nome> -- <comando> [argumentos...]

# Playwright, rodando com npx
claude mcp add playwright -- npx -y @playwright/mcp@latest

# Um servidor que precisa de uma API key no ambiente
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server
```

Sem o `--`, uma opção do servidor como `--port 8080` seria lida como opção do Claude Code e o comando falharia. Outra pegadinha citada na documentação: `--env` aceita vários pares `KEY=value`, então se o nome do servidor vier logo depois, ele é lido como mais um par e rejeitado. Coloque outra opção no meio, como `--transport stdio`, igual ao exemplo acima.

O Claude Code define `CLAUDE_PROJECT_DIR` no ambiente de cada servidor stdio, assim o servidor encontra a raiz do projeto sem depender do diretório de trabalho.

## Adicionar um servidor HTTP remoto

Servidores remotos recebem uma URL em vez de um comando. Adicione headers com `--header` quando o servidor pedir uma API key ou um bearer token:

```bash
# Um servidor hospedado que faz login com OAuth
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Um servidor que usa um token estático
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"
```

O header que você digita aqui fica salvo em texto puro no arquivo de configuração. Para qualquer coisa compartilhada, prefira OAuth ou uma referência `${VAR}` no `.mcp.json`, explicada abaixo.

Se o README do servidor já traz uma definição em JSON, pule as opções e cole com `add-json`. O comando recebe o objeto que ficaria dentro de `mcpServers`, não o arquivo inteiro:

```bash
claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'
```

## Escolha o escopo

Cada `claude mcp add` grava em um de três escopos:

| Escopo | Opção | Salvo em | Quem recebe |
| --- | --- | --- | --- |
| Local (padrão) | `--scope local` | `~/.claude.json`, sob o caminho deste projeto | Só você, só neste projeto |
| Project | `--scope project` | `.mcp.json` na raiz do projeto | Todo mundo que clona o repo |
| User | `--scope user` | `~/.claude.json` | Só você, em todos os projetos |

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

Regra prática: ferramentas pessoais e tudo que leva suas próprias credenciais vão em `user` ou `local`; servidores de que o time inteiro precisa para trabalhar no repo vão em `project`.

Atenção: “local” aqui não é o `.claude/settings.local.json`. Servidores MCP locais ficam em `~/.claude.json`, na sua pasta de usuário.

Quando o mesmo nome está definido em mais de um lugar, o Claude Code usa o de maior prioridade e não mescla campos: primeiro local, depois project, depois user, depois servidores de plugins e, por último, os conectores do claude.ai. Se dois escopos apontam o mesmo nome para endpoints diferentes, `claude mcp list` e `/mcp` avisam.

## Escrever o .mcp.json à mão

Um servidor com escopo project é só um arquivo `.mcp.json` que você pode editar e revisar em pull requests:

```json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    },
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}
```

`${VAR}` é substituído pelo valor de uma variável de ambiente, e `${VAR:-default}` usa um valor padrão quando ela não existe. A expansão funciona em `command`, `args`, `env`, `url` e `headers`, e é assim que você commita o arquivo sem commitar tokens: cada desenvolvedor define `API_KEY` no próprio shell. Se uma variável faltar e não tiver valor padrão, `claude mcp list` e `/mcp` avisam e deixam o texto sem expandir.

Um `"timeout"` por servidor, em milissegundos, define um limite rígido para as chamadas de ferramenta daquele servidor.

## Gerenciar servidores: list, get, remove e /mcp

No shell:

```bash
claude mcp list          # todos os servidores, com status de conexão
claude mcp get notion    # detalhes de um servidor, inclusive por que falhou
claude mcp remove notion # remove do escopo onde está
```

`list` e `get` mostram o detalhe do erro com as credenciais ocultas. Um servidor de projeto que você ainda não aprovou aparece como pendente até você abrir o `claude` no modo interativo e aprová-lo.

Dentro de uma sessão, `/mcp` é o painel de controle. Ele mostra o status e a quantidade de ferramentas de cada servidor, e no menu de um servidor você pode se autenticar, se reautenticar, limpar a autenticação, reconectar ou desativar o servidor sem apagar a configuração. `/mcp reconnect all` tenta de novo todos os servidores com falha de uma vez (Claude Code 2.1.284 ou mais recente).

Servidores conectados trazem mais do que ferramentas. Digite `@` para referenciar recursos de um servidor ao lado dos seus arquivos, e `/` para ver os prompts dele, listados como `/servidor:prompt (MCP)`. As ferramentas se chamam `mcp__<servidor>__<ferramenta>`, e é esse nome que você usa nas regras de permissão e nos [matchers de hooks](/pt/blog/claude-code-hooks-guide/ "Guia de hooks do Claude Code").

## Fazer login em servidores OAuth

Muitos servidores hospedados, como Sentry, Notion ou Linear, usam OAuth em vez de um token estático. Adicione o servidor com `--transport http` e sem header, e depois faça login:

```bash
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
```

No Claude Code, rode `/mcp`, escolha o servidor e clique em **Authenticate**. O navegador abre, você faz login, e o Claude Code guarda o token e o renova. Também dá para fazer pelo shell, sem abrir uma sessão:

```bash
claude mcp login sentry               # abre o navegador
claude mcp login sentry --no-browser  # imprime a URL, para sessões SSH
claude mcp logout sentry              # esquece as credenciais salvas
```

Execuções headless (`claude -p`) não conseguem mostrar uma tela de login, então faça login uma vez no modo interativo antes. Alguns servidores exigem uma porta de callback fixa ou um app OAuth pré-registrado; para eles, passe `--callback-port`, `--client-id` e `--client-secret` ao adicionar o servidor. O secret é pedido com entrada mascarada, ou lido de `MCP_CLIENT_SECRET` no CI.

## Importar servidores do Claude Desktop

Se você já configurou servidores no app Claude Desktop, não precisa digitar tudo de novo:

```bash
claude mcp add-from-claude-desktop
```

Uma janela deixa você escolher quais servidores importar. Em outubro de 2026, isso só funciona no macOS e no WSL. Adicione `--scope user` para importar para a sua configuração de usuário. Nomes de servidor só podem ter letras, números, hífens e underscores, então um servidor do Desktop com espaço no nome é ignorado e reportado, e um nome que já existe ganha um sufixo como `server_1`.

## Solução de problemas

| Sintoma | O que tentar |
| --- | --- |
| O servidor não conecta | `claude mcp get <nome>` para ver o erro, depois **Reconnect** no `/mcp` |
| Servidor lento dá timeout na inicialização | Inicie com `MCP_TIMEOUT=10000 claude` (dez segundos) |
| Chamadas longas de ferramenta são cortadas | `MCP_TOOL_TIMEOUT` para todos os servidores, ou `"timeout"` por servidor no `.mcp.json` |
| Aviso de saída ou resultados truncados | O Claude Code avisa acima de 10.000 tokens e corta em 25.000 por padrão. Aumente com `MAX_MCP_OUTPUT_TOKENS=50000` |
| As opções do servidor são ignoradas ou rejeitadas | Opções do Claude Code antes do nome, comando do servidor depois de `--` |
| Aviso de `${VAR}` no `/mcp` | Defina a variável no shell de onde você inicia o Claude Code, ou adicione `:-default` |
| Servidor ignorado ao carregar | O nome é reservado (`workspace`, `claude-in-chrome`, `computer-use` e mais alguns); renomeie |
| O token funciona no curl, mas não aqui | Procure um espaço ou quebra de linha no fim do token colado; o Claude Code avisa sobre espaços ocultos |

Resultados de texto longos têm um segundo limite: um resultado com mais de 50.000 caracteres é salvo em um arquivo em vez de entrar direto no contexto.

Servidores remotos que caem no meio da sessão são retentados até cinco vezes com intervalo crescente, mas servidores stdio não são retentados automaticamente, então um servidor local que travou precisa ser reconectado pelo `/mcp`.

O contexto é o outro custo a acompanhar. Nos modelos atuais, o Claude Code usa busca de ferramentas (tool search) por padrão: na inicialização só carrega os nomes das ferramentas e as instruções dos servidores, e as definições completas são carregadas quando o Claude precisa delas. Isso deixa uma lista longa de servidores barata, mas cada servidor ainda é mais uma peça que pode falhar ou ser mal usada, então mantenha a lista curta. Em scripts, `--mcp-config <arquivo>` carrega servidores extras para uma única execução, e `--strict-mcp-config` faz o Claude Code usar só esses.

## Segurança: servidores de projeto são código do repo

Um `.mcp.json` em um repo pode iniciar qualquer comando local ou apontar para qualquer URL. É isso que o torna útil para times, e também o motivo de o Claude Code tratá-lo com cuidado:

- **Aprovação primeiro.** Em uma sessão interativa, o Claude Code pergunta antes de usar servidores com escopo project. `claude mcp reset-project-choices` limpa suas respostas anteriores.
- **Um repo não aprova a si mesmo.** Configurações como `enableAllProjectMcpServers` commitadas no `.claude/settings.json` do projeto são ignoradas até você confiar na pasta, e o servidor continua pendente. Aprovações das suas próprias configurações de usuário continuam valendo.
- **Execuções headless não perguntam.** Em `claude -p` e no Agent SDK não existe a pergunta, então os servidores de projeto carregam sem ela. Para bloquear um servidor em qualquer modo, coloque-o em `disabledMcpjsonServers`.
- **As credenciais ficam em casa.** Em `url` e `headers` de um servidor remoto, variáveis sensíveis como `ANTHROPIC_API_KEY` são expandidas como vazias mesmo que estejam definidas, então um projeto não consegue mandar sua chave da Anthropic para o servidor dele sem você perceber.
- **Confie tão pouco no que o servidor devolve quanto no que ele executa.** A documentação da Anthropic avisa que servidores que buscam conteúdo externo podem expor você a [prompt injection](/pt/glossary/prompt-injection/ "Prompt injection"). Prefira modos somente leitura e tokens com permissões mínimas.

Antes de aprovar, leia o `command`, os `args` e a `url` de cada servidor do mesmo jeito que você leria um script `postinstall`. O panorama geral está em [segurança de agentes de código com IA](/pt/blog/ai-coding-agent-security/ "Segurança de agentes de código com IA").

## Quando você usa mais do que o Claude Code

Tudo acima vale por CLI. O Codex guarda seus servidores em `~/.codex/config.toml`, o Gemini CLI no próprio `settings.json`, e cada ferramenta tem seus comandos. Se o Claude Code é o único agente que você usa, `claude mcp add` e um `.mcp.json` commitado bastam, e nada aqui exige outra ferramenta.

Se você usa várias CLIs de código, as listas acabam se desencontrando. É para isso que existe o [gerenciador de MCP](/pt/features/mcp-manager/ "Gerenciador de MCP") do AgentVera, o app desktop que publica este blog:

- **Adicionado uma vez, conectado na inicialização.** Você registra servidores stdio, HTTP e SSE no AgentVera, e eles se conectam quando os agentes iniciam: em todos os agentes, nos que você escolher, nos agentes de um grupo ou em um papel de time. Claude Code, Codex e os outros agentes de CLI com suporte a MCP recebem esses servidores.
- **Em sintonia com a configuração do Claude Code.** Os servidores das configurações do Claude Code e do Codex aparecem com o status deles; você pode importá-los para o AgentVera ou removê-los da CLI, e os servidores do AgentVera também podem ser gravados nas configurações da CLI.
- **Um só login, sem tokens em arquivos.** Servidores remotos passam pelo gateway do AgentVera, você faz login uma vez no app em um servidor OAuth, e a CLI do agente não guarda nenhum header nem token. Variáveis de ambiente e headers secretos ficam no chaveiro do sistema operacional.
- **Custos à vista.** Um teste de conexão lista as ferramentas, prompts e recursos de um servidor com um custo aproximado em tokens por ferramenta.

## Resumindo

Comece com um servidor de que você realmente precisa, adicionado com `claude mcp add` no escopo mais restrito que funcione. Confira com `claude mcp list` ou `/mcp`, faça login com `/mcp` ou `claude mcp login`, e só mova para um `.mcp.json` commitado quando o time inteiro precisar, com os tokens em referências `${VAR}`. Quando algo quebrar, `claude mcp get`, `MCP_TIMEOUT` e `MAX_MCP_OUTPUT_TOKENS` resolvem quase tudo.

Leia mais:

- [O que é um servidor MCP?](/pt/blog/what-is-mcp-server/ "O que é um servidor MCP")
- [Os melhores servidores MCP para agentes de código](/pt/blog/best-mcp-servers-for-coding/ "Os melhores servidores MCP para programar")
- [Gerenciador de MCP](/pt/features/mcp-manager/ "Gerenciador de MCP")
- [Claude Code como agente](/pt/agents/claude-code/ "Claude Code no AgentVera")

## Perguntas frequentes

**Como adiciono um servidor MCP ao Claude Code?** Rode claude mcp add no terminal. Para um servidor local: claude mcp add <nome> -- <comando> [argumentos]. Para um remoto: claude mcp add --transport http <nome> <url>. Depois use claude mcp list, ou /mcp dentro de uma sessão, para conferir se ele conecta.

**Onde o Claude Code guarda os servidores MCP?** Servidores com escopo local (padrão) e user ficam em ~/.claude.json; os locais, sob o caminho do projeto atual. Servidores com escopo project ficam em um arquivo .mcp.json na raiz do projeto, que você pode commitar para o seu time.

**Qual a diferença entre os escopos local, project e user?** Local vale só para você e só neste projeto. Project vale para todo mundo que clona o repo, via .mcp.json. User vale só para você, mas em todos os projetos da sua máquina. Se um nome existe em vários escopos, local vence project, e project vence user.

**Como faço login em um servidor MCP que usa OAuth?** Adicione-o com --transport http, depois rode /mcp no Claude Code e escolha Authenticate, ou use claude mcp login <nome> no shell. O login no navegador conclui o fluxo, e o Claude Code guarda e renova o token para você.

**Por que meu servidor MCP dá timeout ou corta a saída?** Servidores lentos podem precisar de mais tempo para iniciar: abra o Claude Code com MCP_TIMEOUT=10000 para dez segundos. A saída das ferramentas tem limite padrão de 25.000 tokens, com aviso acima de 10.000; aumente o limite com MAX_MCP_OUTPUT_TOKENS.

**É seguro usar o .mcp.json de um repo clonado?** Trate-o como qualquer código que você não escreveu. O Claude Code pede aprovação antes de usar servidores de projeto em uma sessão interativa, e um repo clonado não consegue aprovar os próprios servidores. Leia cada comando e cada URL antes de aceitar.

---

**Sobre o AgentVera.** AgentVera é um app desktop para macOS, Windows e Linux, desenvolvido pela Solviera Teknoloji. Ele roda 18 agentes de programação com IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) lado a lado, por projeto, em terminais reais com as instalações e logins de CLI do próprio usuário. O plano gratuito tem agentes ilimitados. Baixar: https://agentvera.dev/pt/download/ · Preços: https://agentvera.dev/pt/pricing/