Estamos Construyendo Servidores MCP Mal

Cuando la mayoría de los desarrolladores construyen su primer servidor MCP, hacen algo predecible: toman su API REST y envuelven cada endpoint como una herramienta MCP. GET /users se convierte en get_users. POST /orders se convierte en create_order. El mapeo es 1:1, mecánico y equivocado.

Está equivocado porque las APIs REST están diseñadas para desarrolladores que leen documentación, entienden modelos de datos y pueden encadenar múltiples llamadas en su cabeza. Los LLM no funcionan así. Trabajan con descripciones de herramientas, no con documentación.

Cuando mapeas ciegamente REST a MCP, fuerzas al LLM a reconstruir el modelo mental que tu documentación le habría dado a un desarrollador humano. A veces lo logra. A menudo no. Y cuando no, culpas al LLM en lugar del diseño de la herramienta.

El cambio fundamental es este: los endpoints REST modelan recursos. Las herramientas MCP deberían modelar tareas.

Una API REST tiene GET /users/{id}, GET /users/{id}/orders, GET /orders/{id}/items. Tres endpoints, tres llamadas, tres respuestas que el consumidor ensambla.

Un servidor MCP debería tener una herramienta get_user_order_summary que devuelva todo lo que el LLM necesita en una llamada. El LLM preguntó "¿qué pidió este usuario?" — dale la respuesta, no tres piezas de rompecabezas.

Esto se siente incorrecto para puristas de APIs. Viola la normalización. Duplica datos. Pero el consumidor no es un desarrollador escribiendo código limpio — es un LLM que rinde mejor con menos llamadas más completas.

En una API REST, la ruta del endpoint y el método HTTP llevan información semántica. GET /users es obvio. Los desarrolladores pueden a menudo adivinar lo que hace un endpoint antes de leer la documentación.

Los LLM no parsean patrones de URL. Leen descripciones de herramientas. Tu descripción es la única documentación que importa. Si es vaga, el LLM usará la herramienta mal. Si es engañosa, la usará en el momento equivocado.

Escribe descripciones como si estuvieras explicando la herramienta a un colega muy literal sin contexto sobre tu sistema. Di exactamente qué hace, qué devuelve, cuándo usarla y cuándo NO usarla. El caso negativo importa tanto como el positivo.

La mayoría de los servidores MCP tienen descripciones que sacarían una D en una clase de escritura técnica. Esta es la mejora de mayor impacto que puedes hacer.

Un patrón que veo constantemente: un servidor MCP con search_documents, find_documents y query_documents. Tres herramientas que hacen casi lo mismo con parámetros ligeramente diferentes.

Para un desarrollador humano, las diferencias son obvias. Para un LLM, son tres herramientas con descripciones similares que tiene que adivinar cuál usar. Adivina mal aproximadamente el 40% de las veces.

La superposición de herramientas es la fuente número uno de problemas de fiabilidad MCP. La solución es deduplicación despiadada. Si dos herramientas pueden fusionarse sin perder funcionalidad importante, fusiónalas. Agrega parámetros en lugar de agregar herramientas.

Menos herramientas más capaces siempre ganan a muchas herramientas especializadas.

La meta-lección es simple: las herramientas MCP tienen un consumidor diferente que las APIs REST, y diferentes consumidores necesitan diferentes diseños.

Prueba tus herramientas con LLMs reales. No solo "¿la herramienta se ejecuta correctamente?" — sino "¿el LLM elige la herramienta correcta, pasa los parámetros correctos e interpreta la respuesta correctamente?"

Monitorea cómo los LLM realmente usan tus herramientas en producción. Encontrarás patrones sorprendentes — herramientas usadas de maneras inesperadas, herramientas ignoradas porque sus descripciones son ambiguas.

Los mejores servidores MCP no son los que tienen más herramientas o la arquitectura más limpia. Son donde el LLM obtiene la respuesta correcta al primer intento, cada vez. Esa es la única métrica que importa.