Servidor MCP de 360 líneas sin SDK: cinco decisiones que hicieron que el agente dejara de romper enlaces
Tras una respuesta «tool failed», el agente adivina: repite la llamada, cambia los argumentos o se disculpa. El autor de un servicio de enlaces cortos escribió un servidor MCP de 360 líneas en Node.js, sin SDK, que solo actúa como proxy de la API REST del servicio. Los errores los devuelve como un resultado normal de la herramienta, y las operaciones por lotes, con éxito parcial. Su conclusión: las respuestas de la API también deben diseñarse pensando en el modelo.
Procesado por IA desde Habr AI; editado por Hamidun News
Conectar un agente a tu servicio mediante Model Context Protocol (MCP) no es complicado. Lo difícil es lograr que no se confunda, no haga peticiones innecesarias y no estropee los datos. El desarrollador de un servicio de enlaces cortos compartió su experiencia: su servidor MCP ocupa unas 360 líneas de Node.js puro, sin SDK ni dependencias, y casi cada línea apareció después de que Claude Code o Cursor se comportaran de forma inesperada. El escenario es sencillo: el agente redacta un boletín o las release notes, crea él mismo un enlace con etiquetas UTM y luego revisa los clics.
Una capa fina en lugar de una segunda copia de la lógica
El servidor no contiene lógica de negocio propia. Recibe la llamada a la herramienta, consulta la API REST ya existente con una clave y devuelve la respuesta. La validación, los límites y las comprobaciones de seguridad siguen en el lado de la API.
Esto aporta tres ventajas. Las reglas viven en un solo lugar: si cambias un límite o una comprobación de URL, todos los clientes MCP reciben el cambio sin actualizar ningún paquete. El servidor se ejecuta en local con npx y solo necesita la clave y la dirección de la API. Y es fácil de probar, porque es un mapeo «herramienta → petición HTTP».
El transporte también es sencillo. El servidor local se comunica con el cliente mediante stdin y stdout, con mensajes JSON-RPC 2.0, una cadena JSON por línea. Por precaución, el parser también entiende el formato con cabecera Content-Length, como en LSP. Hay dos detalles en los que es fácil tropezar: stdin llega en fragmentos de longitud arbitraria, por lo que hace falta un buffer con el resto sin procesar, y en stdout no se puede escribir nada que no sea protocolo. Un console.log olvidado basta para que el cliente desconecte el servidor en silencio. La depuración debe enviarse a stderr.
Cinco decisiones que resultaron más importantes que las demás
Los errores como datos. Si devuelves un fallo de la API como error JSON-RPC, el cliente suele mostrarle al modelo solo «tool failed». A partir de ahí, el modelo adivina: repite la llamada, cambia los argumentos o se disculpa ante el usuario.
El autor devuelve el error como un resultado normal con la marca isError: true, y el texto llega al contexto. Los errores de protocolo se reservan para fallos reales: método desconocido, herramienta desconocida o JSON no válido. El texto del error está escrito para el modelo: en lugar de un «401» desnudo, aparece «API_KEY is invalid.
Create a key at…» Al recibirlo, el agente normalmente no vuelve a golpear la API, sino que indica al usuario dónde conseguir la clave.
Anotaciones de las herramientas peligrosas. Las herramientas tienen sugerencias como readOnlyHint, destructiveHint, idempotentHint y openWorldHint, y los clientes las usan para decidir cuándo pedir confirmación. Borrar y desactivar un enlace se marcan como destructive; leer la lista y las estadísticas, como de solo lectura. Además, la descripción incluye la frase «This cannot be undone», de modo que el modelo vuelve a preguntar al usuario por su cuenta. Pero esto son solo sugerencias, no una protección. Los límites reales son los permisos de la clave y las comprobaciones en el servidor.
Un manejo predecible de las URL. A los modelos les gusta «corregir» los enlaces. Si el usuario pide añadir utm_source=newsletter y la URL ya tiene utm_source=partner, ¿quién gana? El autor decidió que los parámetros existentes no se sobrescriben y que el ancla #fragment se conserva, porque quien puso esas etiquetas en una campaña ya en marcha lo hizo a propósito. La regla está cubierta por un test sobre la API y descrita en la descripción de la herramienta. La conclusión general: si el modelo puede pasar datos sobrantes o contradictorios, el comportamiento del servidor debe ser determinista y estar documentado.
Éxito parcial en los lotes. La herramienta shorten_urls crea varios enlaces de una vez. Si uno de cada diez no supera la validación, una excepción llevaría al modelo a pensar que no se creó nada, y lo relanzaría todo aunque nueve enlaces ya existan. Por eso la API responde con un objeto con los arrays created y errors, y el servidor lo devuelve como un resultado normal, incluso ante un error HTTP. El modelo solo reintenta las posiciones que fallaron.
Las imágenes como imágenes. Un código QR en texto base64 son varios kilobytes de caracteres sin sentido en el contexto, es decir, tokens y dinero desperdiciados. MCP tiene un tipo de contenido image: el cliente muestra la imagen y, junto a ella, va un breve bloque de texto con el tipo y el tamaño. Con eso basta para que el modelo diga «QR listo, PNG, 4 KB».
Qué haría distinto el autor
La conexión se resuelve con un solo comando: claude mcp add con la clave y la dirección, mediante npx; para Cursor y Claude Desktop, lo mismo se describe en mcp.json. Después, el agente puede recibir instrucciones en texto normal.
El autor reconoce con franqueza las limitaciones del enfoque. Las respuestas de la API deberían haberse diseñado desde el principio pensando en el modelo: las causas de error breves y el éxito parcial explícito también son útiles en integraciones normales. Escribir el protocolo a mano tiene sentido para entenderlo, pero para recursos, prompts y transporte HTTP el SDK oficial ahorra tiempo. Y conviene probar en varios clientes a la vez: Claude Code, Cursor y MCP Inspector muestran los errores de forma distinta y deciden de manera distinta cuándo pedir confirmación.
La conclusión práctica para quien construye MCP sobre su propia API: mantén la lógica en el servidor, escribe los errores como instrucciones para el modelo, marca las operaciones peligrosas y no metas en el contexto lo que el modelo no sabe leer.
- 21 nov 2026Text-to-cad: un agente de IA dibuja piezas de un robot a partir de una descripción y el proyecto suma 26 000 estrellas
- 21 nov 2026El vídeo de Claude jugando a GTA 6 parece un montaje: media hora de control agotó el límite de 5 horas de Pro
- 21 nov 2026Claude Code aceleró la descompilación de Snowboard Kids 2: del 20% al 45% de las funciones en tres meses
- 21 nov 2026Las vacantes de FDE se multiplicaron por 4,6 en un año: qué hace un ingeniero en el cliente
Preguntas frecuentes sobre la noticia
¿Qué se sabe sobre Una capa fina en lugar de una segunda copia de la lógica?
El servidor no contiene lógica de negocio propia. Recibe la llamada a la herramienta, consulta la API REST ya existente con una clave y devuelve la respuesta. La validación, los límites y las comprobaciones de seguridad siguen en el lado de la API. Esto aporta tres ventajas. Las reglas viven en un solo lugar: si cambias un límite o una comprobación de URL, todos los clientes MCP reciben el cambio sin actualizar ningún paquete.
¿Qué se sabe sobre Cinco decisiones que resultaron más importantes que las demás?
Los errores como datos. Si devuelves un fallo de la API como error JSON-RPC, el cliente suele mostrarle al modelo solo «tool failed». A partir de ahí, el modelo adivina: repite la llamada, cambia los argumentos o se disculpa ante el usuario. El autor devuelve el error como un resultado normal con la marca isError: true, y el texto llega al contexto. Los errores de protocolo se reservan para fallos reales: método desconocido, herramienta desconocida o JSON no válido.
¿Qué se sabe sobre Qué haría distinto el autor?
La conexión se resuelve con un solo comando: claude mcp add con la clave y la dirección, mediante npx; para Cursor y Claude Desktop, lo mismo se describe en mcp.json. Después, el agente puede recibir instrucciones en texto normal. El autor reconoce con franqueza las limitaciones del enfoque. Las respuestas de la API deberían haberse diseñado desde el principio pensando en el modelo: las causas de error breves y el éxito parcial explícito también son útiles en integraciones normales.
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.
Lo esencial de la IA — una vez por semana
Siete historias que de verdad importaron, elegidas a mano. Sin ruido ni notas de prensa.
¡Listo! Revisa tu correo para la confirmación.