Como configurar o MCP no Claude Code (passo a passo, do zero)

O Claude Code, sozinho, já lê e escreve arquivos e roda comandos no seu projeto. Mas o trabalho de verdade quase sempre mora em outras ferramentas. O GitHub onde está o código. O navegador que abre o seu site. O banco de dados com os pedidos. O MCP é o que liga o Claude a tudo isso.

Neste guia você vai conectar o seu primeiro servidor em poucos minutos. Pode copiar e colar cada comando.

O que é MCP, sem enrolação

MCP quer dizer Model Context Protocol. É um padrão que deixa o Claude usar ferramentas externas direto, como GitHub, Notion ou o navegador, sem você ficar copiando e colando informação de um lado pro outro.

Pense assim. Sem MCP, o Claude é um funcionário brilhante trancado numa sala. Com MCP, você dá a ele as chaves das outras salas da empresa.

Antes de começar

Você precisa do Claude Code instalado e funcionando no terminal. Se o comando abaixo responde com uma versão, está pronto.

claude --version

O comando que adiciona um servidor

Tudo gira em torno de um comando só. A estrutura é esta:

claude mcp add [--scope local|project|user] [--transport http|stdio|sse] <nome> <url-ou-comando>

Parece muita coisa, mas na prática você só preenche três espaços. O nome que você dá, de onde ele vem, e quem pode usar. Vamos por partes.

Passo 1. Escolha quem vai usar (o escopo)

O escopo decide onde a configuração fica salva e quem enxerga o servidor. São três.

• local (o padrão). Vale só pra você, só neste projeto. Use quando estiver testando.
• project. Fica num arquivo .mcp.json na raiz do projeto e vai pro Git. Todo mundo que clonar o repositório recebe o mesmo servidor. Use pra ferramentas que o time inteiro precisa.
• user. Vale pra você em todos os projetos da máquina. Use pras suas ferramentas pessoais.

Quando dois escopos definem o mesmo servidor, a ordem de prioridade é local, depois project, depois user.

Passo 2. Adicione o servidor

Existem três formas de conexão. Você não precisa decorar, só saber qual exemplo copiar.

Servidor hospedado (HTTP)

É um servidor que já roda numa URL. O mais comum hoje.

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

Servidor local (stdio)

Roda na sua própria máquina, como um navegador controlável ou acesso a arquivos. Tudo depois do -- é o comando que o Claude executa.

claude mcp add playwright -- npx -y @playwright/mcp@latest

Servidor com eventos (SSE)

Menos comum no começo. Serve pra servidores que enviam avisos pro Claude.

claude mcp add --transport sse meu-webhook https://meu-servico.local:8000

Passo 3. Exemplo completo, de ponta a ponta (GitHub)

Digamos que você quer o Claude revisando os seus Pull Requests no GitHub. Com um token de acesso do GitHub em mãos, o comando é este.

claude mcp add --scope user --transport http github \
  https://mcp.github.com/mcp \
  --header "Authorization: Bearer ghp_seu_token_aqui"

Pronto. A partir de agora, em qualquer projeto, você pode pedir:

Revise o PR em github.com/minhaempresa/repo/pull/42

E o Claude passa a enxergar as ferramentas do GitHub. Listar PRs, ler o diff, deixar comentários.

Passo 4. O arquivo .mcp.json (pro time inteiro)

Se você usou o escopo project, a configuração vira um arquivo .mcp.json na raiz do projeto. Ele tem este formato.

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://mcp.github.com/mcp",
      "headers": {
        "Authorization": "Bearer ghp_seu_token_aqui"
      }
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

Como esse arquivo vai pro Git, na primeira vez que alguém do time abre o projeto o Claude pede uma aprovação rápida. É proposital, pra ninguém rodar um servidor sem saber.

Passo 5. Confira se funcionou

Do terminal, fora de uma sessão, rode:

claude mcp list

Você vai ver cada servidor com um status.

MCP Servers (local):
  ✓ github: Connected
  ✓ playwright: Connected
  ! sentry: Needs authentication
  ✗ meu-webhook: Failed to connect

O que cada um quer dizer:

• ✓ Connected. Tudo certo, o Claude já pode usar.
• ! Needs authentication. Falta autorizar (veja abaixo).
• ✗ Failed to connect. URL errada, servidor fora do ar ou token inválido.

Dentro de uma sessão, o comando /mcp abre um menu pra ver as ferramentas, autenticar e checar o status.

/mcp

Se o servidor pede login (OAuth), é aqui que você escolhe Authenticate. O navegador abre, você aprova, e o status vira Connected.

Comandos úteis do dia a dia

# listar tudo
claude mcp list

# ver os detalhes de um servidor
claude mcp get github

# remover
claude mcp remove github

# importar servidores que já estão no Claude Desktop (macOS e WSL)
claude mcp add-from-claude-desktop

Os 3 tropeços mais comuns

1. “No MCP servers configured” do nada. Você adicionou o servidor no escopo local dentro de um projeto e abriu o Claude em outro. A solução é usar o escopo user, que vale em todo lugar, ou adicionar de novo no projeto certo.

2. “Failed to connect”. Quase sempre é a URL ou o token. Para um servidor HTTP, teste a URL com curl -I <url>. Para um servidor local, rode o comando do -- direto no terminal e veja o erro real. Se for lentidão na primeira vez, aumente o tempo limite com MCP_TIMEOUT=60000 claude.

3. Editou o .mcp.json e nada mudou. O Claude lê esse arquivo só quando a sessão começa. Saia com /exit e abra de novo.

Resumindo

Conectar uma ferramenta ao Claude Code é uma linha de comando. Você escolhe o escopo, cola o endereço, confere com claude mcp list e pronto. A partir daí o Claude deixa de ser um assistente isolado e passa a agir nas ferramentas que a sua empresa já usa.

É exatamente esse tipo de ligação que transforma uma curiosidade em automação que poupa horas toda semana. Se quiser, a gente faz esse desenho pro seu negócio e te entrega rodando.

Perguntas frequentes

O que é o MCP no Claude Code?

MCP quer dizer Model Context Protocol. É um padrão que deixa o Claude usar ferramentas externas direto, como GitHub, Notion ou o navegador, sem você copiar e colar informação de um lado para o outro.

Como adicionar um servidor MCP no Claude Code?

Use o comando claude mcp add, informando um nome e o endereço do servidor. Para um servidor hospedado: claude mcp add --transport http nome https://url-do-servidor. Confira depois com claude mcp list.

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

Local vale só para você neste projeto. Project fica num arquivo .mcp.json na raiz e vai para o Git, valendo para o time inteiro. User vale para você em todos os projetos da máquina. Quando há conflito, a prioridade é local, depois project, depois user.

Por que aparece Failed to connect ao listar os servidores?

Quase sempre é a URL ou o token errados. Em servidor HTTP, teste a URL com curl. Em servidor local, rode o comando do -- direto no terminal para ver o erro real. Se for lentidão na primeira conexão, aumente o tempo limite com MCP_TIMEOUT=60000.

É seguro guardar o token no arquivo .mcp.json?

Não. Como esse arquivo vai para o Git, nunca escreva senha ou token de verdade nele. Deixe o token numa variável de ambiente e referencie a variável, em vez de escrever o valor.