Intensivo Grátis 21–22/11Intensivo gratuito de 2 dias em Vibecoding (21–22/11 às 16:00 MSK) · Turma 3 começa 23/11Inscrever-se grátis →Turma 3 (23/11)
LançamentoCódigo / SDK · Pronto p/ usoHabr AI→ original

Servidor MCP de 360 linhas sem SDK: cinco decisões que fizeram o agente parar de quebrar links

Depois de uma resposta "tool failed", o agente fica no palpite: repete a chamada, muda os argumentos, pede desculpas. O autor de um encurtador de links escreveu um servidor MCP de 360 linhas em Node.js, sem SDK, que apenas faz proxy da API REST do serviço. Ele passou a devolver os erros como resultado comum da ferramenta e as operações em lote com sucesso parcial. A conclusão: vale projetar as respostas da API também pensando no modelo.

Processado por IA de Habr AI; editado por Hamidun News
Servidor MCP de 360 linhas sem SDK: cinco decisões que fizeram o agente parar de quebrar links
Fonte: Habr AI. Colagem: Hamidun News.
Ouvir artigo
Ficha técnica e números-chave
ParâmetroDados
Fonte originalHabr AI ↗
Editor-chefe
Os erros chegam com isErrortrue: o modelo lê o motivo e não repete a chamada
Dado-chave #2Os utm_ já existentes no link não são sobrescritos, e a âncora #fragment é preservada
Dado-chave #3O QR code é devolvido com o tipo image, e não como texto base64 de vários quilobytes

Conectar um agente ao seu serviço via Model Context Protocol (MCP) é fácil. O difícil é fazer com que ele não se atrapalhe, não dispare requisições desnecessárias e não estrague dados. O desenvolvedor de um encurtador de links compartilhou sua experiência: o servidor MCP dele tem cerca de 360 linhas em Node.js puro, sem SDK e sem dependências, e quase cada linha surgiu depois que o Claude Code ou o Cursor se comportou de forma inesperada. O cenário é simples: o agente escreve uma newsletter ou release notes, cria por conta própria um link com UTMs e depois consulta os cliques.

Uma camada fina em vez de uma segunda cópia da lógica

O servidor não tem lógica de negócio própria. Ele recebe a chamada da ferramenta, consulta a API REST já existente com a chave e devolve a resposta. Validação, limites e verificações de segurança continuam do lado da API.

Isso traz três vantagens. As regras ficam em um só lugar: se o limite ou a verificação de URL mudar, todos os clientes MCP recebem a alteração sem atualizar o pacote. O servidor roda localmente via npx e precisa apenas da chave e do endereço da API. E ele é fácil de testar: trata-se de um mapeamento "ferramenta → requisição HTTP".

O transporte também é simples. O servidor local conversa com o cliente por stdin e stdout, com mensagens JSON-RPC 2.0, uma linha JSON por mensagem. Por precaução, o parser também entende o formato com cabeçalho Content-Length, como no LSP. Há dois detalhes em que é fácil tropeçar: o stdin chega em pedaços de tamanho arbitrário, então é preciso um buffer com o resto ainda não processado, e no stdout não se pode escrever nada além do protocolo. Um único console.log esquecido e o cliente desconecta o servidor em silêncio. A depuração deve ir para o stderr.

Cinco decisões que pesaram mais que as demais

Erros como dados. Se uma falha da API for devolvida como erro JSON-RPC, o cliente muitas vezes mostra ao modelo apenas "tool failed". Em seguida, o modelo fica no palpite: repete a chamada, muda os argumentos, pede desculpas ao usuário.

O autor passou a devolver o erro como resultado comum, com a flag isError: true, e o texto entra no contexto. Os erros de protocolo ficaram reservados para falhas de verdade: método desconhecido, ferramenta desconhecida, JSON inválido. A mensagem de erro é escrita para o modelo: em vez de um "401" seco, vai "API_KEY is invalid.

Create a key at…" Com isso, o agente normalmente não martela a API de novo e orienta o usuário sobre onde obter a chave.

Anotações em ferramentas perigosas. As ferramentas têm as dicas readOnlyHint, destructiveHint, idempotentHint e openWorldHint, e os clientes as usam para decidir quando pedir confirmação. Excluir e desativar um link estão marcados como destructive; ler a lista e as estatísticas, como read-only. Há ainda a frase "This cannot be undone" na descrição: o próprio modelo pergunta de novo ao usuário. Mas isso são só dicas, não proteção. As restrições reais são as permissões da chave e as verificações no servidor.

Tratamento previsível de URLs. Os modelos adoram "corrigir" links. Se o usuário pede para adicionar utm_source=newsletter e a URL já tem utm_source=partner, qual vence? O autor decidiu: os parâmetros existentes não são sobrescritos e a âncora #fragment é preservada, porque as marcas de uma campanha pronta foram colocadas por alguém de propósito. A regra está fixada em um teste da API e descrita na descrição da ferramenta. A conclusão vale em geral: se o modelo pode enviar dados a mais ou contraditórios, o comportamento do servidor deve ser determinístico e documentado.

Sucesso parcial em lotes. A ferramenta shorten_urls cria vários links de uma vez. Se um de dez não passar na validação, uma exceção faz o modelo concluir que nada deu certo, e ele refaz tudo, embora nove links já tenham sido criados. Por isso a API responde com um objeto com os arrays created e errors, e o servidor o entrega como resultado comum, mesmo em caso de erro HTTP. O modelo repete apenas os itens que falharam.

Imagens como imagens. Um QR code em texto base64 são vários quilobytes de caracteres sem sentido no contexto, ou seja, tokens e dinheiro desperdiçados. O MCP tem o tipo de conteúdo image: o cliente exibe a imagem, e ao lado vai um bloco de texto curto com o tipo e o tamanho. Isso basta para o modelo dizer "QR pronto, PNG, 4 KB".

O que o autor faria diferente

A conexão leva um comando: claude mcp add com a chave e o endereço via npx; no Cursor e no Claude Desktop, o mesmo é descrito no mcp.json. Depois disso, dá para escrever ao agente em texto comum.

O autor aponta com franqueza as limitações da abordagem. As respostas da API deveriam ter sido projetadas para o modelo desde o início: motivos de erro curtos e sucesso parcial explícito são úteis também para integrações comuns. Escrever o protocolo à mão faz sentido para aprender, mas, para resources, prompts e transporte HTTP, o SDK oficial economiza tempo. E é preciso testar desde cedo em vários clientes: Claude Code, Cursor e MCP Inspector mostram os erros de maneiras diferentes e decidem de forma diferente quando pedir confirmação.

A conclusão prática para quem monta um MCP sobre a própria API: mantenha a lógica no servidor, escreva os erros como instruções para o modelo, marque as operações perigosas e não entregue ao contexto o que o modelo não sabe ler.

História

Perguntas frequentes sobre a notícia

O que se sabe sobre Uma camada fina em vez de uma segunda cópia da lógica?

O servidor não tem lógica de negócio própria. Ele recebe a chamada da ferramenta, consulta a API REST já existente com a chave e devolve a resposta. Validação, limites e verificações de segurança continuam do lado da API. Isso traz três vantagens. As regras ficam em um só lugar: se o limite ou a verificação de URL mudar, todos os clientes MCP recebem a alteração sem atualizar o pacote. O servidor roda localmente via npx e precisa apenas da chave e do endereço da API.

O que se sabe sobre Cinco decisões que pesaram mais que as demais?

Erros como dados. Se uma falha da API for devolvida como erro JSON-RPC, o cliente muitas vezes mostra ao modelo apenas "tool failed". Em seguida, o modelo fica no palpite: repete a chamada, muda os argumentos, pede desculpas ao usuário. O autor passou a devolver o erro como resultado comum, com a flag isError: true, e o texto entra no contexto. Os erros de protocolo ficaram reservados para falhas de verdade: método desconhecido, ferramenta desconhecida, JSON inválido.

O que o autor faria diferente?

A conexão leva um comando: claude mcp add com a chave e o endereço via npx; no Cursor e no Claude Desktop, o mesmo é descrito no mcp.json. Depois disso, dá para escrever ao agente em texto comum. O autor aponta com franqueza as limitações da abordagem. As respostas da API deveriam ter sido projetadas para o modelo desde o início: motivos de erro curtos e sucesso parcial explícito são úteis também para integrações comuns.

ZK
Zhemal Khamidun — CPO da Alpina Digital, gerente de produto do AlpinaGPT. Cria produtos de IA desde 2019. O Hamidun News é um projeto pessoal que virou um agregador em produção com mais de 6.000 leitores.
✦ Hands-On AI Engineering · Hamidun Academy

Build & Ship Production AI Agents Without Boilerplate Code

Start your free 72-hour trial at Hamidun Academy (academy.hamidun.com) — interactive lessons on Claude Code & Cursor, live Tech Radar, and production agent templates.

Start 72h Free Trial →Vibe-Coding Intensive
O que você acha?
Carregando comentários…