MCP no Claude Code: o que é e como ligar um servidor

O que é MCP no Claude Code, como adicionar servidores stdio e http, escopos, segredos por variável, permissões mcp__ e o risco de injeção de prompt.

Publicado
Leitura
6 min
Neste post

Uma das coisas que estou estudando no Claude Code é o MCP. A sigla aparece em todo lugar, mas pouca explicação mostra o básico: o que é, como ligar um servidor e o que muda na segurança.

Este post é o resumo do que entendi lendo a documentação oficial, com o olhar de quem usa o Claude Code dentro dos containers do homelab. Se você ainda não conhece os comandos básicos, comece pelo post sobre os comandos com / do Claude Code.

O que é MCP #

MCP (Model Context Protocol) é um padrão aberto para ligar ferramentas de IA a outros sistemas. Um servidor MCP dá ao Claude Code acesso a ferramentas, bancos de dados e APIs que ele não tem por padrão.

A documentação dá uma regra prática boa: vale ligar um servidor quando você se pega copiando dados de outra ferramenta para colar no chat. Em vez de colar, o Claude lê e age direto no sistema.

Pensando em homelab, os exemplos são fáceis de imaginar: ler arquivos de uma pasta fora do projeto, consultar um banco, falar com a API de um serviço. Cada servidor MCP expõe algumas ferramentas, e o Claude decide quando usar cada uma, sempre passando pelas permissões que você definiu.

Os três tipos de conexão #

O servidor MCP pode estar em dois lugares: rodando na sua máquina ou num serviço remoto. Isso define o transporte:

TransporteOnde rodaQuando usar
stdioProcesso local, iniciado pelo Claude CodeFerramentas na própria máquina ou container
httpServidor remotoÉ o recomendado para servidores remotos
sseServidor remotoObsoleto. Use http quando houver

O comando é sempre o claude mcp add. Para um servidor remoto:

claude mcp add --transport http meu-servico https://exemplo.com/mcp

Para um servidor local, o comando que inicia o servidor vem depois de um --:

claude mcp add --transport stdio arquivos \
  -- npx -y @modelcontextprotocol/server-filesystem --read-only /srv/docs

O -- separa as opções do Claude Code (--transport, --env, --scope) das opções do servidor. Tudo que vem depois dele vai para o servidor sem mexer. Sem o --, o Claude Code tentaria ler o --read-only como uma opção dele.

Esse exemplo usa o servidor de arquivos de referência do próprio projeto MCP. Ele só acessa as pastas passadas na linha de comando, e o --read-only faz o servidor nem oferecer as ferramentas de escrita. É um bom primeiro teste: o Claude passa a ler /srv/docs, mas não consegue alterar nada lá. Ele precisa do Node.js instalado, por causa do npx.

Onde a configuração fica: escopos #

Todo servidor tem um escopo, que define onde ele vale e onde fica salvo:

EscopoVale emVai para o git?Fica em
local (padrão)Só no projeto atualNão~/.claude.json
projectSó no projeto atualSim.mcp.json na raiz do projeto
userTodos os seus projetosNão~/.claude.json
claude mcp add --transport http meu-servico --scope project https://exemplo.com/mcp

O escopo project cria um .mcp.json que vai para o repositório. Por segurança, o Claude Code pede aprovação antes de usar um servidor vindo desse arquivo. Se você aprovou algo errado, o claude mcp reset-project-choices zera essas escolhas.

Para gerenciar o que já está configurado:

claude mcp list            # todos os servidores
claude mcp get arquivos    # detalhes de um
claude mcp remove arquivos # remove

Dentro da sessão, o /mcp mostra o status de cada servidor e faz o login nos que pedem OAuth. O login abre no navegador, e os tokens são guardados e renovados sozinhos.

Segredos fora do repositório #

A regra que mais repito no homelab vale aqui também: segredo não vai para o git. Contei as regras no post sobre as regras que dou ao Claude Code.

O .mcp.json aceita variáveis de ambiente, justamente para isso:

{
  "mcpServers": {
    "minha-api": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.exemplo.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

O ${API_KEY} é lido do ambiente na hora de carregar, e o ${VAR:-padrão} usa um valor padrão se a variável não existir. O arquivo pode ir para o git sem a chave.

Dois detalhes da documentação:

  • Se a variável não existir e não houver padrão, a configuração carrega mesmo assim, com o texto ${VAR} literal, e o claude mcp list mostra um aviso.
  • Algumas variáveis de credencial do próprio Claude Code chegam vazias na URL e nos cabeçalhos de servidores remotos. Isso impede que um .mcp.json de terceiros vaze a sua chave para o servidor que ele aponta.

Permissões para ferramentas MCP #

As ferramentas de um servidor MCP passam pelo mesmo sistema de permissões do resto. O nome segue o formato mcp__<servidor>__<ferramenta>:

{
  "permissions": {
    "allow": ["mcp__arquivos__*"],
    "deny": ["mcp__outro-servidor__*"]
  }
}
  • mcp__arquivos__* cobre todas as ferramentas do servidor arquivos.
  • mcp__arquivos__read_text_file cobre só uma ferramenta.
  • Num deny, mcp__* bloqueia todas as ferramentas MCP de todos os servidores. Num allow, esse curinga sem servidor é ignorado: para liberar, é preciso nomear o servidor.

Esse último ponto é um bom desenho. Não dá para liberar “qualquer MCP” sem querer.

O risco que importa: injeção de prompt #

A documentação é direta: confira se confia em cada servidor antes de ligar. Um servidor que busca conteúdo de fora (páginas, e-mails, issues) pode trazer texto escrito para enganar a IA. É a chamada injeção de prompt.

O que eu olharia antes de instalar um servidor MCP:

  1. Quem mantém. Servidor oficial do serviço ou do projeto MCP é diferente de um pacote qualquer.
  2. O que ele consegue fazer. Se só precisa ler, procure um modo só leitura, como o --read-only do servidor de arquivos.
  3. O que ele lê de fora. Quanto mais conteúdo externo, mais cuidado com o que a IA pode ser levada a fazer.
  4. As permissões. Comece sem allow e deixe o Claude pedir. Libere ferramenta por ferramenta conforme confiar.

Um detalhe prático: o Claude Code avisa quando a resposta de uma ferramenta MCP passa de 10 mil tokens e corta em 25 mil por padrão. Para aumentar o limite, existe a variável MAX_MCP_OUTPUT_TOKENS. Antes de subir, porém, vale perguntar se o servidor não está trazendo dados demais.

Resumindo #

  • MCP liga o Claude Code a outros sistemas. Use quando estiver copiando e colando dados de outra ferramenta.
  • http para remoto, stdio para local. O sse está obsoleto.
  • O -- separa as opções do Claude Code das opções do servidor.
  • Escopo local é o padrão. O project vai para o git e pede aprovação.
  • Segredo por variável (${API_KEY}), nunca escrito no .mcp.json.
  • Permissões por servidor: mcp__<servidor>__*, e um deny com mcp__* bloqueia tudo.
  • Confie antes de ligar. Servidor que lê conteúdo de fora traz risco de injeção de prompt.

Meu próximo passo é escolher um servidor que resolva algo real no homelab, em vez de instalar por curiosidade. Quando tiver um caso de uso de verdade, ele vira post.

Fontes e documentação