Source: https://claudetutorial.com/guides/pt-br/como-adicionar-um-servidor-mcp-ao-claude-code-comandos-escopos-e-solucoes [Voltar para Guias](https://claudetutorial.com/guides/pt-br) Builders # Como adicionar um servidor MCP ao Claude Code: comandos, escopos e soluções 27 de outubro de 2026 11 min de leitura --- O jeito comum de conectar o Claude Code a uma ferramenta é ler três páginas de configuração diferentes, copiar um comando ligeiramente errado para o seu sistema e não entender por que nada aparece. O processo de verdade é um comando e uma conferência, desde que você saiba qual tipo de servidor está adicionando. > Todo servidor MCP que você adiciona ao Claude Code se resume a um comando: claude mcp add, seguido de como ele se conecta. Este guia traz os comandos para os três tipos de servidor, explica os escopos que decidem quem recebe o servidor e cobre login, segurança e as soluções para o que dá errado. Se o MCP é novidade para você, comece por [O que é MCP?](https://claudetutorial.com/guides/pt-br/o-que-e-mcp-o-model-context-protocol-explicado-de-forma-simples). ## O que você precisa - Claude Code instalado e funcionando. Se não estiver, veja [Claude Code para iniciantes](https://claudetutorial.com/guides/pt-br/claude-code-para-iniciantes-instale-entre-e-faca-sua-primeira-tarefa) - O endereço do servidor (se for remoto) ou o comando que o inicia (se for local), na documentação do próprio serviço - Uma conta no serviço que você vai conectar Conecte um servidor quando você se pegar copiando dados de outra ferramenta para o chat. Depois de conectado, o Claude pode ler daquele sistema e agir nele diretamente. ## Três tipos de servidor O comando que você usa depende de como o servidor se conecta a você. | Tipo | Como se conecta | Use para | | --- | --- | --- | | **HTTP remoto** | Um endereço web na internet | A maioria dos serviços na nuvem. A escolha recomendada | | **SSE remoto** | Um endereço web com um método mais antigo | Serviços que só oferecem esse método. Obsoleto, então prefira HTTP sempre que possível | | **stdio local** | Um programa que roda na sua máquina | Arquivos locais, bancos de dados e ferramentas | ### Servidor HTTP remoto A forma básica é a mesma para qualquer serviço: ``` claude mcp add --transport http ``` Um exemplo real conecta o Notion: ``` claude mcp add --transport http notion https://mcp.notion.com/mcp ``` Se o servidor exigir um token, passe-o como cabeçalho: ``` claude mcp add --transport http secure-api https://api.example.com/mcp \ --header "Authorization: Bearer your-token" ``` ### Servidor SSE remoto (obsoleto) O método SSE é obsoleto, então use HTTP quando o serviço oferecer. Se um serviço só tiver SSE, o comando usa outro transporte: ``` claude mcp add --transport sse asana https://mcp.asana.com/sse ``` ### Servidor stdio local Um servidor stdio é um programa que roda na sua própria máquina, iniciado pelo Claude Code. A forma básica tem um travessão duplo, e tudo o que vem depois dele é o comando que inicia o servidor: ``` claude mcp add [options] -- [args...] ``` Um exemplo que adiciona um servidor do Airtable com uma chave de API: ``` claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \ -- npx -y airtable-mcp-server ``` Não esqueça o travessão duplo Tudo o que vem depois de `--` é repassado ao servidor sem alteração. Sem ele, o Claude Code tenta ler as flags do próprio servidor como se fossem opções dele, e o comando falha de jeitos confusos. ## Confira se funcionou Depois de adicionar um servidor, confira pelo terminal ou de dentro do Claude Code. Terminal ``` $ claude mcp list$ claude mcp get notion$ claude mcp remove notion ``` Liste todos os servidores configurados, veja os detalhes de um ou remova um. Dentro de uma sessão, digite `/mcp` para ver o status de cada servidor. Você verá um de três estados: conectado, precisa de autenticação ou falha ao conectar. | Status | O que significa | O que fazer | | --- | --- | --- | | Conectado | O servidor está pronto | Peça ao Claude para usá-lo | | Precisa de autenticação | Você ainda não entrou na conta | Rode `/mcp` e siga o login no navegador | | Falha ao conectar | O Claude Code não conseguiu alcançá-lo ou iniciá-lo | Veja as soluções abaixo | ## Entre com OAuth Muitos servidores na nuvem usam OAuth 2.0, o fluxo de "entrar com a sua conta". O caminho mais simples tem dois passos. 1. Adicione o servidor Por exemplo: `claude mcp add --transport http sentry https://mcp.sentry.dev/mcp` 2. Autentique No Claude Code, rode `/mcp` e siga os passos de login no navegador. Pelo shell, você também pode rodar `claude mcp login ` e `claude mcp logout `. Os tokens são guardados com segurança e renovados automaticamente. Para revogar o acesso, use **Clear authentication** (limpar autenticação) no menu do `/mcp`. ## Escopos: quem recebe o servidor Ao adicionar um servidor, você escolhe o escopo dele. O escopo decide quais projetos o enxergam e se a sua equipe o compartilha. | Escopo | Disponível em | Compartilhado com a equipe | Guardado em | | --- | --- | --- | --- | | **Local** (o padrão) | Só o projeto atual | Não | `~/.claude.json` | | **Projeto** | Só o projeto atual | Sim, pelo controle de versão | `.mcp.json` na raiz do projeto | | **Usuário** | Todos os seus projetos | Não | `~/.claude.json` | Escolha um com a flag `--scope`: ``` # Project scope: shared with your team claude mcp add --transport http shared-server --scope project https://example.com/mcp # User scope: available in all your projects claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic ``` Um servidor no escopo de projeto grava um arquivo `.mcp.json` na raiz do projeto, que você inclui no commit para que todos recebam a mesma conexão: ``` { "mcpServers": { "shared-server": { "type": "http", "url": "https://example.com/mcp" } } } ``` Se o mesmo nome de servidor aparece em mais de um escopo, o Claude Code conecta uma vez só, usando a definição da fonte de maior precedência: primeiro o local, depois o de projeto, depois o de usuário. Vence primeiro Vence por último 1. Local Só este projeto, só você, guardado em ~/.claude.json 2. Projeto Compartilhado com a equipe pelo .mcp.json 3. Usuário Todos os seus projetos, só você, guardado em ~/.claude.json Use o escopo de projeto para ferramentas de que a equipe toda precisa, o de usuário para as suas ferramentas pessoais e o local quando estiver testando. Quando você abre um projeto que tem um `.mcp.json` de outra pessoa, o Claude Code pede a sua aprovação antes de usar os servidores dele numa sessão interativa. Para zerar essas escolhas de aprovação, rode `claude mcp reset-project-choices`. ## Servidores populares que você pode adicionar hoje Estes exemplos vêm da documentação oficial. Leia sempre a página do próprio serviço para ver o endereço atual. | Serviço | Comando | | --- | --- | | Sentry (erros) | `claude mcp add --transport http sentry https://mcp.sentry.dev/mcp` | | Stripe (pagamentos) | `claude mcp add --transport http stripe https://mcp.stripe.com` | | GitHub (revisões de código) | `claude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer YOUR_GITHUB_PAT"` | | Notion | `claude mcp add --transport http notion https://mcp.notion.com/mcp` | | PostgreSQL pelo DBHub | `claude mcp add --transport stdio db -- npx -y @bytebase/dbhub --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"` | No caso do banco de dados, repare no nome de usuário: `readonly`. Dê ao Claude uma conta de banco que só pode ler. Essa única escolha evita o erro mais caro que você poderia cometer. Você também pode explorar os conectores revisados no diretório da Anthropic, em claude.ai/directory. E se você adicionou um conector no claude.ai, ele já está disponível no Claude Code quando você entra com a sua conta do Claude. ## Fique seguro Um servidor MCP dá ao Claude acesso a um sistema, e alguns servidores buscam conteúdo de fora, como páginas web ou tickets escritos por desconhecidos. Confirme que você confia em cada servidor Servidores que buscam conteúdo externo podem expor você à injeção de prompt: textos escritos para enganar uma IA e fazê-la agir de um jeito que você não pediu. Adicione apenas servidores de fontes em que você confia e olhe o que o Claude pretende fazer com eles. - O servidor vem da documentação do próprio serviço, não de um post qualquer - Os bancos de dados usam uma conta somente leitura - Os tokens ficam em cabeçalhos ou variáveis de ambiente, nunca num arquivo que vai para o commit - Você trabalha num modo de permissão em que vê o que o Claude faz com as ferramentas Esse último ponto está ligado a quanto o Claude faz sem perguntar. Veja [Modos de permissão e modo plan do Claude Code, explicados](https://claudetutorial.com/guides/pt-br/modos-de-permissao-e-modo-plan-do-claude-code-explicados) para decidir isso. Dentro do Claude Tutorial Confiar numa ferramenta é uma decisão, não um padrão Avaliar quais sistemas merecem acesso, e para quais ações, é uma habilidade que vale muito além do código, e o app a pratica com cenários reais. Em breve [DISPONÍVEL NO Google Play](https://play.google.com/store/apps/details?id=com.claudetutorial.mobile) ## Limites e ajustes Dois limites ajudam a explicar comportamentos que, de outro modo, parecem estranhos. - **Resultados grandes.** O Claude Code mostra um aviso quando a saída de uma ferramenta passa de 10.000 tokens e limita a saída a 25.000 tokens por padrão. Para aumentar o limite, defina a variável `MAX_MCP_OUTPUT_TOKENS`, por exemplo `MAX_MCP_OUTPUT_TOKENS=50000`. - **Servidores lentos.** Para mudar quanto tempo o Claude Code espera um servidor iniciar, defina `MCP_TIMEOUT`. Por exemplo, `MCP_TIMEOUT=10000 claude` permite dez segundos. A busca de ferramentas vem ligada por padrão, para que o seu contexto não se encha com a descrição de todas as ferramentas de uma vez. Rode `/context` para ver o que está ocupando espaço. ## Quando não funciona | O que você vê | Causa provável | Solução | | --- | --- | --- | | O servidor não aparece no `claude mcp list` | Foi adicionado em outro escopo ou projeto | Rode `claude mcp list` no projeto em que você o adicionou, ou adicione com `--scope user` | | O `/mcp` mostra precisa de autenticação | Você não entrou na conta | Rode `/mcp` e siga os passos no navegador, ou `claude mcp login ` | | O `/mcp` mostra falha ao conectar | Endereço errado, servidor fora do ar ou comando de início que falha | Confira a URL na documentação do serviço. Para um servidor local, rode o comando dele no terminal para ver o erro | | As flags de um servidor local são rejeitadas | Falta o travessão duplo | Acrescente `--` antes do comando do servidor | | Funciona em um projeto mas não em outro | O escopo local vale para um projeto só | Adicione de novo com `--scope user`, ou com o escopo de projeto para uma equipe | | O Claude ignora um servidor de projeto | A aprovação do `.mcp.json` foi recusada | Rode `claude mcp reset-project-choices` e aprove de novo | | A saída vem cortada | O padrão de 25.000 tokens | Aumente o `MAX_MCP_OUTPUT_TOKENS` | Quando nada disso resolver, peça ajuda ao Claude Code: cole o erro e pergunte o que ele significa. Rodar `/doctor` também confere a sua configuração. ## Perguntas frequentes ### Como adiciono um servidor MCP ao Claude Code? Rode `claude mcp add --transport http ` para um servidor remoto, ou `claude mcp add -- ` para um local. Depois rode `/mcp` dentro do Claude Code para ver o status e entrar na conta. ### Onde o Claude Code guarda os servidores MCP? Os servidores de escopo local e de usuário ficam em `~/.claude.json`. Os de escopo de projeto ficam num arquivo `.mcp.json` na raiz do projeto, que você pode incluir no commit. ### Qual a diferença entre os escopos local, de projeto e de usuário? O local vale para o projeto atual e só para você. O de projeto vale para o projeto atual e é compartilhado com a equipe. O de usuário vale para todos os seus projetos e só para você. ### Como removo um servidor MCP? Rode `claude mcp remove `. Para sair de um servidor sem removê-lo, use `claude mcp logout `. ### O que significa o travessão duplo no claude mcp add? Ele separa as opções do próprio Claude Code do comando que inicia o servidor. Tudo o que vem depois é repassado ao servidor sem alteração. ### Os servidores MCP são seguros? Só tão seguros quanto os servidores que você escolhe e o acesso que você dá. Use servidores confiáveis, contas de banco somente leitura e um modo de permissão em que você veja o que o Claude faz. ### Posso usar no Claude Code os conectores do meu claude.ai? Sim. Os conectores que você adiciona no claude.ai ficam disponíveis no Claude Code, no terminal e nas sessões na nuvem, quando você entra com a sua conta do Claude. ## Seu checklist de MCP no Claude Code - `claude mcp list` mostra o servidor e `/mcp` o mostra como conectado - Você escolheu o escopo de propósito: local para testar, de projeto para a equipe, de usuário para você - As credenciais ficam em cabeçalhos ou variáveis de ambiente, não em arquivos que vão para o commit - Tudo o que toca dados que você não consegue restaurar usa acesso somente leitura ## Continue lendo - [O que é MCP? O Model Context Protocol explicado de forma simples](https://claudetutorial.com/guides/pt-br/o-que-e-mcp-o-model-context-protocol-explicado-de-forma-simples) para entender a ideia por trás. - [Como adicionar conectores no Claude: diretório, URL personalizada e segurança](https://claudetutorial.com/guides/pt-br/como-adicionar-conectores-no-claude-diretorio-url-personalizada-e-seguranca) para o mesmo assunto nos apps do Claude. - [Boas práticas do Claude Code: hábitos que dão melhores resultados](https://claudetutorial.com/guides/pt-br/boas-praticas-do-claude-code-habitos-que-dao-melhores-resultados) para trabalhar bem depois que as ferramentas estiverem conectadas. - [CLAUDE.md explicado: ensine o seu projeto ao Claude Code uma vez só](https://claudetutorial.com/guides/pt-br/claude-md-explicado-ensine-seu-projeto-ao-claude-code-uma-vez) para dizer ao Claude como usar as ferramentas conectadas no seu projeto.