Conecte o Claude Code a outras ferramentas com MCP

O Claude Code já vem com ferramentas para arquivos, para o terminal e para a web. O MCP (Model Context Protocol) é o jeito de dar mais ferramentas a ele: uma busca em uma documentação, acesso a um sistema de tickets, um banco de dados, um navegador ou um script seu. Cada uma delas vem de um servidor MCP e, depois que o servidor está conectado, o Claude chama as ferramentas dele do mesmo jeito que chama as que já vêm de fábrica.

Este guia conecta um servidor hospedado, depois monta um pequeno servidor seu em Python e termina na parte que mais importa em uma máquina que você administra: o que a configuração MCP de um repositório pode rodar na sua máquina, e quando o Claude Code pergunta antes.

Dois tipos de servidor

• Servidores remotos rodam em outro lugar, e o Claude Code acessa esses servidores por HTTP. Muitos serviços oferecem um, geralmente com login pelo navegador.
• Servidores locais são programas que o Claude Code inicia na sua máquina e com os quais conversa pela entrada e saída padrão (stdio). Cada um alcança tudo o que a sua conta de usuário alcança: seus arquivos, seus bancos de dados, seus comandos.

Os dois são adicionados com claude mcp add, no terminal, e não dentro de uma sessão.

Seu primeiro servidor

A documentação do Claude Code tem o próprio servidor MCP, com uma busca na documentação. Ele não exige conta, então é um bom primeiro teste.

1. 1

   Adicione o servidor

   Terminal · seu usuário

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

2. 2

   Confira se ele conecta

   Terminal · seu usuário

   $ claude mcp get claude-code-docs

   Saída

   claude-code-docs:
     Scope: Local config (private to you in this project)
     Status: ✔ Connected
     Type: http

3. 3

   Use o servidor

   Claude Code

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

claude-code-docs é um nome que você escolhe. Ele identifica as ferramentas do servidor e é como você se refere a ele em outros comandos. Normalmente você não precisa citar o servidor no pedido, porque o Claude escolhe sozinho a ferramenta certa. Aqui citamos o nome para garantir que a resposta venha do servidor, e não de uma busca na web. O pedido pode ser em português. Usamos inglês porque é assim que você vai encontrar a maioria dos exemplos.

No nosso teste, o Claude chamou a ferramenta search_claude_code_docs do servidor e respondeu com base na página que encontrou, com o link para ela.

claude mcp list mostra todos os servidores com o status de cada um. Para remover um, rode claude mcp remove claude-code-docs. Dentro de uma sessão, /mcp mostra a mesma lista e permite reconectar, fazer login ou desligar um servidor.

Onde o servidor fica salvo

claude mcp add salva o servidor em um de três escopos:

• Local (o padrão): só você, só neste projeto. Fica no ~/.claude.json, na entrada da pasta do projeto.
• Projeto (--scope project): todo mundo que trabalha no projeto. Fica em um arquivo .mcp.json na raiz do projeto, que vai para o commit.
• Usuário (--scope user): só você, em todos os seus projetos. Também fica no ~/.claude.json.

Coloque um servidor que precisa de senha ou de token no escopo local ou de usuário, para que o segredo nunca vá parar no repositório. Se um servidor do projeto precisar de um, o .mcp.json pode ler o valor de uma variável de ambiente, por exemplo "Authorization": "Bearer ${API_KEY}".

Escreva um pequeno servidor seu

Um servidor local é só um programa que lê requisições na entrada padrão e escreve as respostas na saída padrão. Este tem uma única ferramenta, que mostra o uso de disco e de memória. Ele usa só a biblioteca padrão do Python, então não há nada para instalar.

#!/usr/bin/env python3
"""A minimal MCP server over stdio: one tool that reports disk and memory use."""
import json, subprocess, sys

def reply(id, result):
    print(json.dumps({"jsonrpc": "2.0", "id": id, "result": result}), flush=True)

TOOLS = [{
    "name": "disk_and_memory",
    "description": "Disk use of / and memory use of this server",
    "inputSchema": {"type": "object", "properties": {}},
}]

for line in sys.stdin:
    msg = json.loads(line)
    method, id = msg.get("method"), msg.get("id")
    if method == "initialize":
        reply(id, {
            "protocolVersion": "2025-06-18",
            "capabilities": {"tools": {}},
            "serverInfo": {"name": "server-info", "version": "1.0.0"},
        })
    elif method == "tools/list":
        reply(id, {"tools": TOOLS})
    elif method == "tools/call":
        out = subprocess.run("df -h /; echo; free -h", shell=True,
                             capture_output=True, text=True).stdout
        reply(id, {"content": [{"type": "text", "text": out}]})
    elif id is not None:
        err = {"code": -32601, "message": "Method not found"}
        print(json.dumps({"jsonrpc": "2.0", "id": id, "error": err}), flush=True)

O Claude Code manda três tipos de requisição para ele: initialize quando conecta, tools/list para saber quais ferramentas existem e tools/call quando o Claude usa uma. A description da ferramenta é o que o Claude lê para decidir quando ela serve para um pedido, então escreva-a em linguagem simples.

Isso basta para entender como o MCP funciona e para empacotar um ou dois scripts. Para algo maior, use um dos SDKs oficiais indicados no final, que cuidam das partes do protocolo que este arquivo deixa de fora.

Adicione o servidor com o caminho completo do arquivo:

$ claude mcp add server-info -- python3 /home/voce/server-info.py

Tudo o que vem depois de -- é o comando que inicia o servidor. Sem o --, o Claude Code lê as opções do seu programa como se fossem dele e sai com erro. No nosso teste, uma opção que era do programa foi recusada com:

Error: unknown option '--verbose'

Depois, peça em uma sessão:

> Use the server-info server to tell me the disk and memory use of this machine

Permissões das ferramentas MCP

Cada ferramenta MCP tem um nome formado pelo nome do servidor e pelo nome da ferramenta: mcp__server-info__disk_and_memory. No modo Manual (default), o Claude Code pergunta antes de rodar uma ferramenta MCP, do mesmo jeito que faz com um comando do terminal, a não ser que uma regra libere a ferramenta.

Rodamos o pedido acima com claude -p no modo Manual, sem nenhuma regra. A ferramenta foi bloqueada, e a execução respondeu:

Claude requested permissions to use mcp__server-info__disk_and_memory, but you haven't granted it yet.

Com uma regra de liberar, a mesma execução passou. Coloque a regra no .claude/settings.json ou no ~/.claude/settings.json:

{
  "permissions": {
    "allow": ["mcp__server-info"]
  }
}

• mcp__server-info libera todas as ferramentas desse servidor.
• mcp__server-info__disk_and_memory libera só essa ferramenta.
• mcp__server-info__get_* libera as ferramentas cujo nome começa com get_.

As regras ask e as regras de bloqueio funcionam do mesmo jeito. Uma regra de bloqueio para mcp__* desliga todas as ferramentas MCP de todos os servidores.

Os servidores não lotam o contexto

Você pode imaginar que cada servidor conectado ocupa espaço em todas as conversas. Por padrão, o Claude Code carrega só os nomes das ferramentas no início, e o Claude busca a descrição completa de uma ferramenta quando precisa dela. Nas nossas execuções de teste, o primeiro passo do Claude foi sempre uma chamada ToolSearch procurando a ferramenta MCP, e só depois a ferramenta em si. Por isso, adicionar servidores custa pouco, embora remover os que você não usa mais continue sendo uma boa faxina.

O que pode lotar o contexto é a resposta de uma ferramenta. O Claude Code avisa quando um resultado MCP passa de 10.000 tokens. Acima de 25.000, ele salva o resultado em um arquivo e passa o caminho para o Claude. Você pode aumentar o limite de 25.000 com a variável de ambiente MAX_MCP_OUTPUT_TOKENS.

Servidores MCP do repositório de outra pessoa

Um servidor local é um programa, e o .mcp.json de um projeto diz qual programa rodar. Se você clonar um repositório e abrir o Claude Code nele, o .mcp.json pode iniciar um programa na sua máquina. É por isso que o Claude Code pergunta antes, em uma sessão interativa.

Testamos isso com uma pasta que nunca tinha sido marcada como confiável, com um .mcp.json cujo servidor gravava um pequeno arquivo no momento em que iniciava, para ver se ele rodava.

Em uma sessão interativa, o Claude Code mostra primeiro a caixa de confiança de sempre. Essa caixa não diz nada sobre servidores MCP. Depois que você aceita, uma segunda tela mostra o nome do servidor:

New MCP server found in this project: repo-info
 MCP servers may execute code or access system resources. All tool calls
 require approval. Learn more in the MCP documentation.
 Use this MCP server
 Use this and all future MCP servers in this project
❯ Continue without using this MCP server

A opção segura já vem selecionada. Apertar Esc também conta como recusa, e o Claude Code guarda essa escolha: no nosso teste, ele gravou o servidor no .claude/settings.local.json, em disabledMcpjsonServers. Para o Claude Code perguntar de novo, rode claude mcp reset-project-choices. Enquanto você não escolher, claude mcp list mostra o servidor como ⏸ Pending approval.

Em uma execução com claude -p, não há ninguém para responder, então o Claude Code não pergunta. No nosso teste, um claude -p simples naquela pasta nunca marcada como confiável iniciou na hora o servidor do repositório, e o arquivo dele apareceu. A documentação diz o mesmo: em execuções com -p e em sessões do Agent SDK, os servidores do projeto carregam sem perguntar.

Um servidor que você já recusou continua desligado em todos os modos. No nosso teste, depois da recusa acima, claude -p na mesma pasta não iniciou o servidor.

Mais dois pontos da documentação:

• Um repositório não consegue aprovar os próprios servidores antes de você confiar na pasta. As aprovações que vêm no .claude/settings.json do projeto são ignoradas até você confiar na pasta.
• Quando um .mcp.json usa variáveis de ambiente no endereço ou nos cabeçalhos de um servidor remoto, as suas credenciais do Claude e da nuvem, como ANTHROPIC_API_KEY, entram vazias. Um .mcp.json não consegue mandar essas credenciais para um servidor que ele indique.

Existe mais um risco, em servidores remotos ou locais: um servidor que busca páginas da web, emails ou tickets pode entregar ao Claude um texto escrito por um desconhecido, e esse texto pode conter instruções. Conecte servidores em que você confia, e mantenha os que leem conteúdo de fora longe das sessões que podem mexer no que importa para você.

Quando um servidor não conecta

• ✘ Failed to connect em um servidor local: rode você mesmo o comando dele no terminal. Se ele iniciar e ficar esperando, o programa funciona, então compare o comando com claude mcp get <nome>. Um -- faltando é a causa mais comum.
• ! Needs authentication: o servidor pede login. Abra /mcp em uma sessão, escolha o servidor e depois Authenticate, ou rode claude mcp login <nome>. Em uma máquina sem navegador, esse comando mostra um link para você abrir no seu computador.
• O servidor nem aparece: um servidor de escopo local pertence à pasta onde você o adicionou. Rode claude mcp add de novo a partir do projeto certo, ou adicione com --scope user.
• A primeira inicialização é lenta: servidores iniciados com npx baixam um pacote na primeira vez. O Claude Code espera 30 segundos por padrão. MCP_TIMEOUT=60000 claude dá um minuto para eles.
• Mudanças no .mcp.json não têm efeito: o Claude Code lê o arquivo quando a sessão começa. Saia e entre de novo.

Fontes

• Connect Claude Code to tools via MCP, documentação do Claude Code (em inglês)
• Connect to MCP servers, documentação do Claude Code (em inglês)
• Configure permissions, documentação do Claude Code (em inglês)
• Build an MCP server, documentação do Model Context Protocol, com os SDKs oficiais (em inglês)