Ligar o Claude Code a outras ferramentas com MCP

O Claude Code traz ferramentas para ficheiros, para a shell e para a web. O MCP (Model Context Protocol) é a forma de lhe dar mais: uma pesquisa numa documentação, acesso a um gestor de tarefas, uma base de dados, um browser, ou um script teu. Cada uma destas vem de um servidor MCP e, depois de o servidor estar ligado, o Claude chama as ferramentas dele como chama as que já traz.

Este guia liga um servidor alojado, depois constrói um pequeno servidor teu em Python, e acaba na parte que mais conta numa máquina de que cuidas: o que a configuração MCP de um repositório pode correr na tua máquina, e quando é que o Claude Code te pergunta primeiro.

Dois tipos de servidor

• Servidores remotos correm noutro sítio e o Claude Code chega a eles por HTTP. Muitos serviços têm um, muitas vezes com início de sessão no browser.
• Servidores locais são programas que o Claude Code arranca na tua máquina e com quem fala pela entrada e saída padrão (stdio). Cada um chega a tudo aquilo a que a tua conta de utilizador chega: os teus ficheiros, as tuas bases de dados, os teus comandos.

Ambos se acrescentam com claude mcp add, no terminal, e não dentro de uma sessão.

O teu primeiro servidor

A documentação do Claude Code tem o seu próprio servidor MCP, com uma pesquisa na documentação. Não precisa de conta, por isso é um bom primeiro teste.

1. 1

   Acrescenta-o

   Terminal · o teu utilizador

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

2. 2

   Confirma que liga

   Terminal · o teu utilizador

   $ claude mcp get claude-code-docs

   Resultado

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

3. 3

   Usa-o

   Claude Code

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

claude-code-docs é um nome que escolhes. Serve de etiqueta às ferramentas do servidor e é assim que te referes a ele noutros comandos. Normalmente não precisas de dizer o nome do servidor no pedido, porque o Claude escolhe sozinho a ferramenta certa. Aqui dizemo-lo para garantir que a resposta vem do servidor e não de uma pesquisa na web. O pedido pode ser em português. Usamos inglês porque é assim que vais encontrar a maior parte dos exemplos.

No nosso teste, o Claude chamou a ferramenta search_claude_code_docs do servidor e respondeu a partir da página que encontrou, com a ligação para ela.

claude mcp list mostra todos os servidores com o seu estado. Para tirar um, corre claude mcp remove claude-code-docs. Dentro de uma sessão, /mcp mostra a mesma lista e deixa-te voltar a ligar, iniciar sessão ou desligar um servidor.

Onde fica guardado o servidor

claude mcp add guarda o servidor num de três âmbitos:

• Local (o predefinido): só tu, só neste projeto. Fica em ~/.claude.json, na entrada da pasta do projeto.
• Projeto (--scope project): toda a gente que trabalha no projeto. Fica num ficheiro .mcp.json na raiz do projeto, que vai para o commit.
• Utilizador (--scope user): só tu, em todos os teus projetos. Também fica em ~/.claude.json.

Um servidor que precise de uma palavra-passe ou de um token fica no âmbito local ou de utilizador, para o segredo nunca ir parar ao repositório. Se um servidor de projeto precisar de um, o .mcp.json pode ir buscá-lo a uma variável de ambiente, por exemplo "Authorization": "Bearer ${API_KEY}".

Escrever um pequeno servidor teu

Um servidor local é só um programa que lê pedidos da entrada padrão e escreve as respostas na saída padrão. Este tem uma única ferramenta, que mostra o uso do disco e da memória. Usa só a biblioteca padrão do Python, por isso 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-lhe três tipos de pedido: initialize quando liga, tools/list para saber que 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, por isso escreve-a de forma simples.

Isto chega para perceber como funciona o MCP e para embrulhar um ou dois scripts. Para algo maior, usa um dos SDK oficiais indicados no fim, que tratam das partes do protocolo que este ficheiro deixa de fora.

Acrescenta-o com o caminho completo do ficheiro:

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

Tudo o que vem depois de -- é o comando que arranca o servidor. Sem o --, o Claude Code lê as opções destinadas ao teu programa como se fossem dele e para. No nosso teste, uma opção que pertencia ao programa foi recusada com:

Error: unknown option '--verbose'

Depois, pede-o numa 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 feito do nome do servidor e do nome da ferramenta: mcp__server-info__disk_and_memory. No modo Manual (default), o Claude Code pergunta antes de correr uma ferramenta MCP, tal como faz com um comando da shell, a não ser que uma regra a autorize.

Corremos 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 autorizar, a mesma execução passou. Põe a regra no .claude/settings.json ou no ~/.claude/settings.json:

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

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

As regras ask e as regras de bloqueio funcionam da mesma maneira. Uma regra de bloqueio para mcp__* desliga todas as ferramentas MCP de todos os servidores.

Os servidores não enchem o contexto

Podias pensar que cada servidor ligado ocupa espaço em todas as conversas. Por predefinição, o Claude Code só carrega os nomes das ferramentas no início, e o Claude vai buscar 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 à procura da ferramenta MCP, e só depois a ferramenta em si. Por isso, acrescentar servidores sai barato, embora tirar os que já não usas continue a ser boa arrumação.

O que pode encher o contexto é a resposta de uma ferramenta. O Claude Code avisa quando um resultado MCP passa dos 10 000 tokens. Acima dos 25 000, guarda o resultado num ficheiro e dá ao Claude o caminho. Podes subir o limite dos 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 que programa correr. Se clonares um repositório e abrires lá o Claude Code, o .mcp.json dele pode arrancar um programa na tua máquina. É por isso que o Claude Code pergunta primeiro, numa sessão interativa.

Testámos isto com uma pasta que nunca tinha sido marcada como de confiança, com um .mcp.json cujo servidor escreve um pequeno ficheiro no momento em que arranca, para vermos se corria.

Numa sessão interativa, o Claude Code mostra primeiro a caixa de confiança habitual. Essa caixa não diz nada sobre servidores MCP. Depois de a aceitares, um segundo ecrã diz 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 escolhida. Carregar em Esc também conta como não, e o Claude Code lembra-se disso: no nosso teste, escreveu o servidor no .claude/settings.local.json, em disabledMcpjsonServers. Para voltares a ser perguntado, corre claude mcp reset-project-choices. Enquanto não escolheres, claude mcp list mostra o servidor como ⏸ Pending approval.

Numa execução com claude -p, não há ninguém a quem perguntar, por isso o Claude Code não pergunta. No nosso teste, um claude -p simples nessa pasta nunca marcada como de confiança arrancou logo o servidor do repositório, e o ficheiro 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 pergunta.

Um servidor que já recusaste fica desligado em todos os modos. No nosso teste, depois da recusa acima, claude -p na mesma pasta não o arrancou.

Mais dois pontos da documentação:

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

Há mais um risco, em servidores remotos ou locais: um servidor que vai buscar páginas web, emails ou pedidos de suporte pode entregar ao Claude texto escrito por um desconhecido, e esse texto pode trazer instruções. Liga servidores em que confias, e mantém os que leem conteúdo de fora longe das sessões que podem mexer em coisas que te importam.

Quando um servidor não liga

• ✘ Failed to connect num servidor local: corre tu o comando dele no terminal. Se arrancar e ficar à espera, o programa funciona, por isso compara o comando com claude mcp get <nome>. Um -- em falta é a causa habitual.
• ! Needs authentication: o servidor quer que inicies sessão. Abre /mcp numa sessão, escolhe o servidor e depois Authenticate, ou corre claude mcp login <nome>. Numa máquina sem browser, esse comando mostra uma ligação para abrires no teu computador.
• O servidor nem aparece: um servidor de âmbito local pertence à pasta onde o acrescentaste. Corre de novo claude mcp add a partir do projeto certo, ou acrescenta-o com --scope user.
• O primeiro arranque é lento: os servidores lançados com npx descarregam um pacote da primeira vez. O Claude Code espera 30 segundos por predefinição. MCP_TIMEOUT=60000 claude dá-lhes um minuto.
• As alterações ao .mcp.json não fazem nada: o Claude Code lê o ficheiro quando a sessão começa. Sai e volta a entrar.

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 SDK oficiais (em inglês)