O que é um servidor MCP — introdução para quem desenvolve

Se você vive lendo sobre "MCP", provavelmente já percebeu que o assunto passou rápido de curiosidade para encanamento padrão de dev tooling. Este post explica o que exatamente é um servidor MCP, como ele conversa com um cliente de IA e o que um bom servidor expõe versus o que fica de fora. O foco é dev, não marketing.

O problema que o MCP resolve

Assistentes de IA são bons com texto. Ruins com ferramentas. Quando você pede ao Claude ou ao Cursor para te ajudar a depurar um 401, eles só sabem o que você colou no chat. Se precisam olhar um log, uma requisição ou uma tabela, você copia manualmente. O modelo ganha uma janela de contexto grande, mas um conhecimento raso do seu sistema real.

Model Context Protocol (MCP) é a resposta da Anthropic para esse problema. É um protocolo para um assistente de IA ("cliente") conversar com um programa externo ("servidor") que expõe informação e operações locais. O cliente pergunta "quais ferramentas você tem?"; o servidor responde. O cliente chama uma ferramenta; o servidor executa e devolve resultado. Sem colagem.

Na prática, um servidor MCP é um processo que conhece uma coisa — um banco, um sistema de arquivos, um proxy de depuração — e mostra essa coisa para o assistente via uma superfície pequena e estruturada de ferramentas. O cliente não precisa virar especialista no seu sistema; só precisa chamar list_items ou get_detail quando o usuário faz uma pergunta sobre o seu sistema.

A arquitetura em 30 segundos

Três papéis:

• Host — o aplicativo de IA onde você digita (Claude Desktop, Cursor, Windsurf, Zed).
• Cliente — o componente dentro do host que fala o protocolo MCP.
• Servidor — o processo externo que expõe ferramentas, recursos e prompts.

Quando o host sobe, ele lê um arquivo de configuração que lista servidores MCP para iniciar. Para cada servidor, o host cria o processo, conecta via um transporte, envia uma chamada initialize e pede o manifesto de ferramentas. Quando você faz uma pergunta e o modelo decide que precisa de uma tool, o host encaminha a chamada ao servidor via o mesmo transporte, aguarda o resultado e injeta tanto a chamada quanto o resultado na conversa.

Transportes: stdio e HTTP

O MCP roda sobre dois transportes.

stdio. O cliente cria o servidor como subprocesso e fala pelo stdin/stdout do processo. Mensagens JSON-RPC vão num sentido, respostas voltam no outro. É o modelo padrão do Claude Desktop. Vantagens: zero socket de rede, zero porta pra abrir, nenhum dado atravessa a rede. O servidor morre quando o host sai. Para ferramentas locais como "leia o meu tráfego capturado", stdio é a escolha certa.

HTTP. O servidor escuta numa porta HTTP, normalmente no loopback (127.0.0.1). O cliente conecta como cliente HTTP e troca mensagens em JSON. Serve para dois casos: clientes que não conseguem criar subprocessos (navegador, serviço remoto), e servidores que precisam ficar vivos entre conversas do host. A desvantagem: você abre uma porta. Se sua ferramenta tem dados sensíveis, prefira stdio.

O Rockxy expõe as duas. O Claude Desktop usa stdio por padrão; para clientes que não conseguem, existe uma porta HTTP local restrita ao loopback. Nenhuma das duas vias sai do seu Mac.

Ferramentas, recursos e prompts

Um servidor MCP pode expor três tipos de coisa.

Tools (ferramentas) são chamadas de função: o modelo decide chamar, o servidor executa, devolve o resultado. É a parte mais usada. Uma tool tem nome, descrição, esquema JSON de entrada e saída. Pense "list_flows" ou "get_flow_detail" no Rockxy, "search_files" num servidor de filesystem, "run_query" num servidor de banco.

Resources (recursos) são dados nomeados por URI que o modelo lê. O cliente lista recursos por prefixo, lê um ou mais e injeta o conteúdo no contexto. Boa escolha quando você quer mostrar um documento, um schema ou um arquivo de log — algo que o modelo deveria ler, não invocar.

Prompts são templates pré-escritos que o usuário pode escolher num menu. O servidor diz "eu tenho um prompt chamado depurar webhook falho"; o cliente mostra na UI; quando escolhido, o servidor retorna uma mensagem (com parâmetros) que o host injeta na conversa. Útil para receitas reutilizáveis.

A maioria dos servidores MCP de dev começa com tools. Recursos vêm depois. Prompts ficam no final, muitas vezes opcionais.

O que um bom servidor MCP expõe

A tentação é expor tudo. Todas as tabelas, todos os endpoints, todos os campos. Na prática, servidores grandes e difusos tornam o modelo inseguro — ele não sabe qual ferramenta usar quando. Servidores pequenos e opinados com três a cinco tools bem nomeadas são mais fáceis de operar para o modelo.

Exemplos que funcionam:

• Um verbo claro por tool. list_flows lista. get_flow_detail pega um. replay_request refaz. diff_flows compara. Sem ambiguidade sobre qual chamar.
• Esquemas de entrada pequenos. Filtros opcionais com bons defaults. Nunca obrigue o modelo a preencher dez parâmetros pra ter uma resposta útil.
• Saídas estruturadas. Devolva JSON que o modelo consiga ler mecanicamente, não strings com formatação humana bonita.
• Limites explícitos. "até N resultados", "truncar body em 1 MB". O modelo se adapta se os limites forem visíveis.

Exemplos que quebram:

• Uma mega-tool. execute_anything(query) é tentador mas vira uma caixa preta. O modelo não aprende o shape do seu sistema.
• Saídas só em prosa. "A requisição 42 falhou com 401 no endpoint de autenticação às 14h30." é legível mas não composável. Devolva campos.
• Operações destrutivas sem controle. Se a tool muda estado, deixe isso óbvio no nome (delete_*) e documente no esquema. Idealmente, dê um modo dry-run.

Segurança: o que vaza, o que não vaza

MCP não tem um modelo de segurança embutido além do que o transporte oferece. stdio é seguro na medida em que o processo filho é seguro. HTTP no loopback é seguro na medida em que o loopback não seja exposto para fora. Em ambos os casos, o servidor vê tudo que uma tool call pedir.

Duas implicações práticas.

Primeiro, o servidor deve minimizar a superfície. Se sua tool de banco só precisa de SELECT, não dê ao servidor credenciais com DELETE. Princípio de menor privilégio aplicado ao processo MCP.

Segundo, pense no que o cliente de IA faz com a saída. O seu servidor pode rodar inteiramente local, mas o cliente (Claude Desktop, Cursor) envia trechos da saída para o endpoint do modelo remoto. É lá que a decisão de privacidade acontece de fato. Se você expõe chaves de API ou dados de pessoas, o provedor do modelo vai vê-los. Estamos trabalhando para que o Rockxy tenha uma camada de redação antes de qualquer saída ir para um cliente; por enquanto, você escolhe quais sessões abrir quando o MCP está ativo.

Como é um servidor MCP mínimo

A forma mais curta de um servidor MCP é um processo que:

1. Sobe, lê stdin e escreve stdout.
2. Responde a initialize com versão do protocolo e capacidades.
3. Responde a tools/list com um array de tools (nome, descrição, schema de input).
4. Responde a tools/call executando a tool pedida e devolvendo o resultado.

SDKs oficiais em Python e TypeScript fazem o roteamento do protocolo para você. Você só escreve a lógica das tools.

Quando construir um servidor MCP — e quando não construir

Construa quando você tem um sistema com estado que se beneficia de consulta conversacional: um proxy de depuração, um banco local, um log, um filesystem, um índice de busca. A IA faz perguntas abertas; o servidor responde com fatos estruturados.

Não construa quando o que você precisa já é uma API HTTP pública. Se o seu "servidor" só envolve uma chamada REST, a camada MCP não agrega. O modelo pode chamar a API direto via outro mecanismo.

E, como regra geral, não construa se ninguém no seu time vai usar. Um servidor MCP só existe quando está ligado. Valide demanda antes de codificar.

O que o Rockxy expõe e por quê

O servidor MCP do Rockxy tem quatro tools: list_flows, get_flow_detail, replay_request e diff_flows. O suficiente para que o Claude liste, leia, refaça e compare flows HTTP — os quatro verbos que você naturalmente quer quando está depurando uma API.

O escopo é limitado ao arquivo de sessão aberto. Quer limitar o que o Claude enxerga? Abra só a sessão relevante. Quer dar acesso amplo? Abra o histórico inteiro. A UI do Rockxy é o controle de acesso.

Tudo isso roda local, via stdio, sob AGPL-3.0. Se você quiser ver o código do servidor MCP, ele está no mesmo repositório do app principal. Antes de conectar a qualquer assistente de IA, dá para ler exatamente o que está exposto.

Para ligar na prática, veja como conectar o Claude Desktop ao Rockxy em 3 minutos.