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
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:
| Transporte | Onde roda | Quando usar |
|---|---|---|
stdio | Processo local, iniciado pelo Claude Code | Ferramentas na própria máquina ou container |
http | Servidor remoto | É o recomendado para servidores remotos |
sse | Servidor remoto | Obsoleto. 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:
| Escopo | Vale em | Vai para o git? | Fica em |
|---|---|---|---|
local (padrão) | Só no projeto atual | Não | ~/.claude.json |
project | Só no projeto atual | Sim | .mcp.json na raiz do projeto |
user | Todos os seus projetos | Nã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 oclaude mcp listmostra 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.jsonde 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 servidorarquivos.mcp__arquivos__read_text_filecobre só uma ferramenta.- Num
deny,mcp__*bloqueia todas as ferramentas MCP de todos os servidores. Numallow, 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:
- Quem mantém. Servidor oficial do serviço ou do projeto MCP é diferente de um pacote qualquer.
- O que ele consegue fazer. Se só precisa ler, procure um modo só leitura, como o
--read-onlydo servidor de arquivos. - O que ele lê de fora. Quanto mais conteúdo externo, mais cuidado com o que a IA pode ser levada a fazer.
- As permissões. Comece sem
allowe 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.
httppara remoto,stdiopara local. Osseestá obsoleto.- O
--separa as opções do Claude Code das opções do servidor. - Escopo
localé o padrão. Oprojectvai 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 umdenycommcp__*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.