SpyBara
Go Premium

mcp-quickstart.md 2026-10-19 23:58 UTC to 2026-10-20 23:00 UTC

This page contains 215 additions and 249 deletions.

2026
Thu 1 23:59 Thu 15 23:58 Tue 20 23:00 Wed 21 23:02 Thu 22 22:58 Fri 23 22:59 Wed 28 23:57 Fri 30 23:01

Conectar a servidores MCP

Adicione um servidor MCP ao Claude Code, verifique a conexão e encontre a configuração no disco.

O Model Context Protocol (MCP) permite que o Claude Code use ferramentas além do seu conjunto integrado, como pesquisar um rastreador de problemas, consultar um banco de dados ou controlar um navegador da web. Essas ferramentas vêm de servidores MCP, que são executados em sua máquina ou como serviços hospedados.

Este guia o orienta através da conexão de um servidor MCP de ponta a ponta com a CLI do Claude Code. Ao final, você terá um servidor conectado e respondendo, saberá onde sua configuração reside no disco e saberá como corrigir os erros de conexão mais comuns.

[!NOTE]

Você também pode adicionar servidores MCP de outras superfícies, incluindo o aplicativo desktop, VS Code e a web. Consulte Conectar de outras superfícies.

Para cada forma de conectar e configurar servidores MCP no Claude Code, consulte a referência MCP.

Antes de começar

Certifique-se de que você tem:

  • Claude Code instalado e autenticado
  • Um terminal aberto em um diretório de projeto. Qualquer diretório funciona, incluindo um vazio.

Adicionar e verificar um servidor

O exemplo abaixo conecta ao servidor MCP de documentação do Claude Code, um servidor hospedado com busca de texto completo sobre os documentos do Claude Code. Ele não requer autenticação ou nenhuma configuração especial, portanto funciona bem como primeiro servidor para testar o fluxo de configuração.

As etapas são as mesmas para qualquer servidor: adicione-o, verifique o status da conexão e use-o em uma sessão, com uma etapa de limpeza opcional no final. Alguns servidores adicionam uma etapa, como um login no navegador, mostrado em Exemplos adicionais de servidor MCP. Para mais servidores para conectar, navegue pelo Diretório Anthropic.

1. Adicionar o servidor MCP

Registre o servidor com o Claude Code. Execute isto em seu terminal, não dentro de uma sessão claude: você está configurando o servidor antes de iniciar uma conversa.

claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

As partes do comando:

  • claude mcp add: registra um servidor com o Claude Code.
  • --transport http: o servidor é hospedado em uma URL em vez de ser executado como um processo local.
  • claude-code-docs: um nome que você cria. Chamar o mesmo servidor de docs funcionaria de forma idêntica. O Claude Code usa o nome que você escolher para rotular as ferramentas do servidor na saída do Claude e para se referir ao servidor em comandos como claude mcp remove.
  • https://code.claude.com/docs/mcp: a URL onde o servidor é hospedado.

O comando imprime uma confirmação como Added HTTP MCP server claude-code-docs with URL: https://code.claude.com/docs/mcp to local config, seguida por uma linha File modified: mostrando o arquivo de configuração que foi escrito. A parte local config significa que o servidor está registrado para você, neste projeto: se você iniciar o Claude Code em um projeto diferente, este servidor não está ativo lá. Para registrar um servidor uma vez para todos os seus projetos, adicione-o no escopo do usuário, coberto em Alterar escopo do servidor.

2. Verificar o status da conexão

Confirme que o servidor aparece em sua lista de servidores e verifique seu status:

claude mcp list

O servidor aparece com um indicador de status:

Status Significado
✔ Connected Pronto para usar. Isto é o que você deve ver para claude-code-docs
! Connected · tools fetch failed O servidor conectou mas não conseguiu listar suas ferramentas. Execute claude mcp get <name> para obter o detalhe do erro
! Needs authentication O servidor é alcançável mas precisa de um login no navegador, ou um token passado com --header. Consulte Conectar um servidor que requer login
✘ Failed to connect O servidor não respondeu. Consulte Troubleshooting
✘ Connection error A tentativa de conexão lançou um erro. Consulte Troubleshooting
⏸ Pending approval (run `claude` to approve) Um servidor com escopo de projeto que você ainda não aprovou. Consulte Editar .mcp.json diretamente
⊘ Disabled for this project (re-enable via /mcp) Um servidor desativado para este projeto pela lista disabledMcpServers do projeto. Consulte Desativar um servidor sem removê-lo

Alguns consoles Windows legados, como o console padrão no Windows 10, não suportam esses glifos Unicode e mostram √ e × no lugar de ✔ e ✘.

3. Usar o servidor

Inicie uma sessão e peça ao Claude para usar o novo servidor pelo nome:

claude

Use the claude-code-docs server to look up what MCP_TIMEOUT does

[!NOTE]

Você normalmente não precisa nomear um servidor em seu prompt, já que o Claude escolhe ferramentas relevantes por conta própria. Nomeá-lo aqui garante que a demonstração passe pelo novo servidor em vez de outra ferramenta, como web fetch, que poderia responder a mesma pergunta.

Se o Claude Code pedir permissão na primeira vez que o Claude chamar o servidor, aprove-a. A chamada de ferramenta na saída do Claude é rotulada com o nome do servidor, que é como você confirma que a resposta veio do servidor MCP em vez do conhecimento integrado do Claude.

4. Remover o servidor

Esta etapa é opcional. Quando terminar de experimentar, você pode remover o servidor:

claude mcp remove claude-code-docs

O comando confirma com Removed MCP server "claude-code-docs" from local config e uma linha File modified: mostrando o arquivo que foi atualizado.

[!NOTE]

Cada servidor conectado ocupa espaço na janela de contexto do Claude porque seus nomes de ferramentas e instruções do servidor são carregados em cada sessão. Remover servidores que você não usa mais mantém esse espaço livre.

Onde os servidores são salvos

O comando claude mcp add escreve os detalhes do servidor em um arquivo de configuração. Por padrão, ele registra o servidor no escopo local: privado para você, ativo apenas no projeto atual. Passe --scope user para registrá-lo uma vez para todos os seus projetos, ou --scope project para compartilhá-lo com colegas de equipe. Alterar escopo do servidor percorre ambos.

[!NOTE]

claude mcp add funciona da mesma forma em cada shell, incluindo PowerShell e Command Prompt. Dentro de uma sessão claude, use o comando /mcp para verificar e gerenciar servidores que você já adicionou.

Existem outras formas de adicionar um servidor, cada uma com sua própria seção:

Encontre sua configuração no disco

O comando claude mcp add escreve o servidor em um dos três escopos, armazenados em dois arquivos, dependendo da flag --scope. Você não precisa editar esses arquivos diretamente, mas saber onde eles estão ajuda na depuração e controle de versão.

Escopo Arquivo Disponível para
local ~/.claude.json, sob a entrada para este projeto Apenas você, apenas este projeto. O padrão
project .mcp.json na raiz do seu projeto Todos que clonam o projeto
user ~/.claude.json, sob a chave mcpServers de nível superior Apenas você, todos os projetos

No Windows, ~/.claude.json resolve para %USERPROFILE%\.claude.json, tipicamente C:\Users\YourName\.claude.json. Se você definiu CLAUDE_CONFIG_DIR, o Claude Code lê .claude.json de dentro desse diretório.

Execute claude mcp get claude-code-docs para ver qual escopo contém a definição de um servidor. Para como os escopos interagem quando o mesmo servidor é definido em mais de um, consulte Escopos de instalação MCP.

Alterar escopo do servidor

O escopo de um servidor é fixo quando você o adiciona, portanto alterar o escopo significa remover a entrada e readicioná-la no novo. Ambos os casos abaixo começam removendo a entrada local do primeiro passo a passo, para que o servidor tenha apenas uma definição. Se você já o removeu no final desse passo a passo, pule este comando:

claude mcp remove claude-code-docs --scope local

Usar um servidor em todos os seus projetos

Readicione o servidor no escopo user para torná-lo ativo em cada projeto que você abre, ainda privado para você:

claude mcp add --scope user --transport http claude-code-docs https://code.claude.com/docs/mcp

Compartilhar um servidor com sua equipe

Readicione o servidor no escopo project, que escreve em .mcp.json na raiz do projeto:

claude mcp add --scope project --transport http claude-code-docs https://code.claude.com/docs/mcp

Confirme .mcp.json no controle de versão. Colegas de equipe que clonam o repositório e iniciam o Claude Code veem um prompt para aprovar o servidor, então ele se conecta para eles também.

Exemplos adicionais de servidor MCP

O primeiro passo a passo usou um servidor hospedado que se conecta sem nenhum login. Os exemplos abaixo cobrem as outras duas formas comuns, com o mesmo fluxo de adicionar, verificar, usar.

Adicionar um servidor local

Um servidor stdio local é um programa que o Claude Code inicia como um subprocesso em sua máquina, em vez de um serviço que ele alcança por uma URL. Use um para ferramentas que precisam de acesso a recursos locais como um navegador, seu sistema de arquivos ou um socket de banco de dados.

O servidor MCP Playwright é um bom para tentar: ele dá ao Claude um navegador que ele pode navegar, clicar e ler, e não precisa de nenhuma conta. Ele é executado através de npx, portanto requer Node.js 18 ou posterior.

1. Adicionar o servidor Playwright

Registre o servidor com o comando que o Claude Code deve executar para iniciá-lo:

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

Este comando difere do exemplo hospedado de três formas:

  • Não há flag --transport, porque servidores locais usam o transporte padrão stdio.
  • Tudo após o separador -- é o comando que o Claude Code executa para iniciar o servidor.
  • -y diz ao npx para instalar o pacote sem solicitar.

O comando imprime uma confirmação como Added stdio MCP server playwright with command: npx -y @playwright/mcp@latest to local config, seguida por uma linha File modified: mostrando o arquivo de configuração que foi escrito.

Playwright controla qualquer Chrome já instalado em sua máquina. Para usar um navegador diferente, anexe --browser com o nome do navegador, por exemplo --browser firefox, após @playwright/mcp@latest.

2. Verificar a conexão

A confirmação Added significa que a entrada foi salva, não que o comando é executado. Verifique a conexão:

claude mcp list

A primeira verificação pode mostrar ✘ Failed to connect enquanto npx baixa o pacote, portanto aguarde um momento e execute novamente. Assim que o download terminar, o status muda para ✔ Connected. Se ainda mostrar ✘ Failed to connect após alguns retentativas, consulte Troubleshooting.

3. Usar o navegador

Dê ao Claude uma tarefa que precisa do navegador:

Use playwright to open https://example.com and tell me the page title

Uma janela do navegador abre para que você possa vê-lo funcionar, e as chamadas de ferramenta na saída do Claude são rotuladas com o nome do servidor playwright e a ação, como browser_navigate.

Tente apontá-lo para seu servidor de desenvolvimento local para verificar se uma página ainda é renderizada após uma alteração, ou peça que ele percorra um relatório de bug passo a passo.

Conectar um servidor que requer login

Serviços hospedados como Sentry, Linear e Notion executam seus servidores MCP atrás de OAuth: você adiciona a URL do servidor e depois faz login através de seu navegador.

As etapas abaixo usam Sentry como exemplo. Para conectar um serviço diferente, substitua sua URL, que você pode encontrar no Diretório Anthropic ou na documentação do serviço.

1. Adicionar o servidor

O comando add é o mesmo que para o servidor de documentação, com a URL do Sentry:

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

Após adicionar, claude mcp list mostra o servidor com ! Needs authentication. Isto é esperado: a próxima etapa completa o login.

2. Autenticar em seu navegador

Inicie uma sessão do Claude Code e abra o painel MCP:

/mcp

Selecione sentry da lista, pressione Enter e escolha Authenticate. Seu navegador abre para a página de login do Sentry. Aprove a conexão lá.

De volta ao Claude Code, o status do servidor muda para conectado. Se o login falhar ou o navegador não abrir, consulte Troubleshooting.

3. Usar o servidor

Peça ao Claude algo que precisa do serviço, como What Sentry projects do I have access to?, e procure por chamadas de ferramenta rotuladas com o nome do servidor sentry em sua saída.

Servidores que autenticam com um token estático em vez de OAuth pegam o token no momento da adição com --header "Authorization: Bearer <token>". Consulte o exemplo do GitHub para uma versão trabalhada.

Editar .mcp.json diretamente

Cada arquivo na tabela de escopo usa o mesmo formato JSON para entradas de servidor. Esta seção edita .mcp.json, o arquivo de escopo de projeto. É o que mais vale a pena escrever à mão porque é verificado no repositório, onde funciona como configuração como código para sua equipe.

Crie .mcp.json na raiz do seu projeto. O exemplo abaixo define ambos os servidores deste guia, o servidor de documentação hospedado alcançado por HTTP e o servidor Playwright como um processo stdio local:

{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

Os campos diferem por tipo de servidor:

  • Para servidores HTTP, url é o endpoint que o Claude Code se conecta.
  • Para servidores stdio, command e args são o programa que ele executa.

Após salvar o arquivo, inicie uma nova sessão do Claude Code no projeto. O Claude Code lê .mcp.json na inicialização.

A primeira vez que o Claude Code vê um servidor com escopo de projeto, ele pede que você o aprove. O prompt existe para que um repositório que você clona não possa iniciar processos em sua máquina sem seu consentimento. Aprove o prompt, ou execute /mcp para aprovar depois se você o perdeu.

Depois de aprovado, execute /mcp e verifique se os servidores aparecem como conectados. Se um mostrar um erro em vez disso, consulte Troubleshooting.

Conectar de outras superfícies

Este guia usa os comandos CLI claude mcp, mas cada superfície do Claude Code pode se conectar a servidores MCP:

Troubleshooting

Se um servidor não se conectar, verifique seu status com /mcp dentro de uma sessão ou claude mcp list do seu shell, depois combine o sintoma abaixo. O painel /mcp também permite que você se reconecte ou autentique sem sair da sessão.

/mcp shows No MCP servers configured

O Claude Code não encontrou nenhum servidor para o diretório atual. As causas mais comuns:

  • Você executou claude mcp add de um projeto diferente. Servidores com escopo local estão vinculados ao projeto onde você os adicionou: a raiz do repositório, ou o diretório exato se você não estava em um repositório git. Readicione o servidor do projeto em que você está agora, ou adicione-o com --scope user para que não esteja vinculado a um projeto.
  • Você editou um arquivo de configuração no caminho errado. Os arquivos corretos são ~/.claude.json e <project>/.mcp.json. O Claude Code não lê caminhos como ~/.claude/.mcp.json, ~/.claude/config/mcp.json, ~/.claude/mcp.json, ou %APPDATA%\Claude\mcp.json. Para servidores com escopo de usuário, execute claude mcp add --scope user, que escreve na chave mcpServers em ~/.claude.json; para servidores com escopo de projeto, edite .mcp.json na raiz do projeto.
  • Você escreveu uma entrada malformada em .mcp.json. O Claude Code pula essa entrada e ainda carrega as outras. Execute claude mcp list do seu shell e procure pelo aviso de análise, que nomeia o campo ofensivo.

Status shows Failed to connect or Connection error

Ambos os status significam que o servidor não iniciou ou a URL não respondeu. Eles também podem aparecer para servidores HTTP que rejeitam o token que você configurou em headers.Authorization; um servidor que quer um token que você não configurou mostra ! Needs authentication em vez disso, coberto em Conectar um servidor que requer login.

Seu primeiro passo depende de qual status você vê:

  • Failed to connect: comece com o detalhe de falha no próprio status. claude mcp list e claude mcp get <name> mostram o status HTTP ou código de erro e qualquer texto de erro que o servidor retornou, que frequentemente nomeia o problema diretamente, como um cabeçalho ausente ou um token rejeitado. Antes da v2.1.219, Failed to connect mostrava apenas o status simples, e você precisava das verificações curl e comando mais adiante nesta seção para encontrar a causa.
  • Connection error: O Claude Code não anexa nenhum detalhe a este status em nenhuma versão, então vá direto para as verificações curl e comando mais adiante nesta seção.

Se o detalhe apontar para uma credencial ou URL, também verifique os avisos na saída claude mcp list. O Claude Code sinaliza valores de configuração com espaço em branco oculto à esquerda ou à direita, uma causa comum de falhas de autenticação após colar um token.

Se um servidor HTTP retorna 404 Not Found, o Claude Code mostra MCP endpoint not found at <origin>. Check the URL in your MCP config. quando você seleciona o servidor em /mcp. A mensagem nomeia a origem da URL, como https://mcp.example.com, sem seu caminho, então execute claude mcp get <name> para ver a URL completa que você configurou. Compare seu caminho com o caminho do endpoint MCP documentado do servidor, depois execute claude mcp remove <name> e readicione com a URL correta. Antes da v2.1.219, a mensagem incluía o caminho da URL também, e antes da v2.1.191, um 404 mostrava uma mensagem genérica Error POSTing to endpoint sem a URL.

Para servidores HTTP, confirme que a URL é alcançável de sua máquina:

curl -I https://mcp.sentry.dev/mcp

No PowerShell, use curl.exe em vez de curl para que a solicitação vá para o binário curl real em vez do alias Invoke-WebRequest.

A resposta diz qual tipo de problema você tem:

  • Um 404 ou 405: o servidor está ativo. Muitos endpoints MCP respondem apenas a solicitações POST, portanto isto ainda confirma que a URL é alcançável de sua máquina.
  • Um 401 ou 403: o servidor está ativo e você precisa autenticar. Use o login no navegador em Conectar um servidor que requer login, ou para servidores que pegam um token em vez disso, como o do GitHub, passe-o com --header "Authorization: Bearer <token>" no comando claude mcp add.
  • Nenhuma resposta: verifique a URL e sua rede.

Para servidores stdio, execute o comando configurado diretamente em seu terminal para ver o erro subjacente. Para o servidor Playwright deste guia, execute:

npx -y @playwright/mcp@latest

O que acontece a seguir diz onde o problema está:

  • O comando inicia e aguarda entrada: o servidor em si funciona.

    Execute claude mcp get <name> e confirme que o comando mostrado lá corresponde ao que você acabou de executar. Se o comando mostrado diferir do que você digitou, você provavelmente omitiu o separador -- antes do comando do servidor. Remova o servidor e readicione-o com -- no lugar. Se você escreveu .mcp.json à mão, verifique sua sintaxe e localização. Antes da v2.1.285, claude mcp get não imprimia nenhuma linha Command para uma entrada stdio salva sem um campo type, como uma entrada .mcp.json escrita à mão. Nessas versões, execute claude mcp list em vez disso, que imprime a linha de comando de qualquer forma.

  • O comando erros: a mensagem nomeia o que está faltando, como Node.js ou um navegador.

Connection timed out at startup

O servidor levou mais tempo que o timeout de inicialização padrão de 30 segundos. A primeira execução de um servidor stdio pode ser lenta enquanto npx baixa o pacote. Aumente o limite com a variável de ambiente MCP_TIMEOUT, em milissegundos:

MCP_TIMEOUT=60000 claude

No PowerShell, defina a variável antes do comando na mesma linha:

$env:MCP_TIMEOUT = "60000"; claude

Antes da v2.1.299, algumas conexões com servidores HTTP que estavam ativos atingiam o timeout na inicialização independentemente de MCP_TIMEOUT. Se você usa uma dessas versões e um servidor HTTP que está ativo ainda atinge o timeout depois que você aumenta o limite, atualize o Claude Code.

Server already exists

Você já adicionou um servidor com esse nome no mesmo escopo. Remova a entrada existente primeiro ou escolha um nome diferente:

claude mcp remove claude-code-docs

Se o nome existe em mais de um escopo, remove relata exists in multiple scopes. Passe --scope para escolher qual cópia deletar, por exemplo claude mcp remove claude-code-docs --scope local.

Server connects but no tools appear

Execute /mcp dentro de uma sessão e selecione o servidor para ver sua lista de ferramentas. Se a lista estiver vazia, o servidor iniciou mas não registrou nenhuma ferramenta, o que geralmente significa que está faltando uma variável de ambiente necessária como uma chave de API.

Passe a variável com --env KEY=value em claude mcp add, ou no campo env da entrada .mcp.json do servidor. A documentação do servidor lista as variáveis que ele precisa.

Antes da v2.1.302, /mcp mostrava o status tools fetch failed para um servidor usando a revisão de protocolo 2026-07-28 que omitia resultType, ttlMs ou cacheScope de suas respostas. Se você usa uma dessas versões e um servidor mostra esse status, atualize o Claude Code.

Changes to .mcp.json don't take effect

O Claude Code lê .mcp.json na inicialização da sessão. Saia e reinicie a sessão após editar o arquivo.

Se seus servidores ainda não aparecerem, execute claude mcp list e procure por um aviso de análise. O Claude Code pula entradas malformadas e mostra o campo ofensivo lá.

Se você rejeitou anteriormente o servidor quando solicitado, redefina as aprovações do projeto:

claude mcp reset-project-choices

OAuth sign-in fails or browser doesn't open

Execute /mcp, selecione o servidor e escolha Authenticate novamente. Se o navegador não abrir automaticamente, copie a URL mostrada no terminal e abra-a manualmente. Consulte Autenticar com servidores MCP remotos para portas de callback fixas e credenciais pré-configuradas.

Próximos passos

Com um servidor conectado, explore o resto do que o MCP permite: