Bitrix24 enumeró ocho errores típicos al desarrollar servidores MCP para LLMs

Un desarrollador del equipo de IA de Bitrix24 ha publicado un análisis práctico de los errores que más frecuentemente rompen los servidores MCP para LLM. La idea principal es simple: MCP parece una capa determinista sobre una API, pero esta capa es gestionada por un modelo no determinista, por lo que los enfoques de ingeniería convencionales regularmente fallan aquí.

Donde todo se rompe

El primer problema es la autorización. En la especificación, todo se ve limpio: hay OAuth, campos claros y un flujo esperado. En la práctica, diferentes clientes MCP lo implementan de manera desigual: en algunos lugares la autorización funciona parcialmente, en otros con extensiones personalizadas, y en algunos casi no funciona en absoluto. Para servidores stdio locales esto no es tan crítico, pero tan pronto como el servidor sale en línea, comienza la fragmentación. Por eso los equipos a menudo terminan con una opción menos elegante pero estable: tokens pre-emitidos que el usuario agrega manualmente a la configuración.

La segunda gran trampa es el deseo de simplemente envolver Swagger en MCP uno a uno. Para un desarrollador, esto parece lógico: cada endpoint de API se convierte en una herramienta separada. Para el modelo, esto es una trampa de selección. Cuando tiene decenas de herramientas similares, comienza a confundir escenarios, elige comandos incorrectamente y comete errores en los parámetros. Se vuelve aún peor donde necesitas pasar por una larga cadena de acciones: encontrar un usuario, recordar el ID, crear una tarea, luego agregar un observador. Un humano lo hará bien, pero un modelo pierde fácilmente el estado a mitad de camino.

• Los clientes implementan la autorización de manera diferente, por lo que el mismo servidor se comporta de manera impredecible.
• Un gran conjunto de herramientas reduce la probabilidad de que el modelo seleccione la correcta.
• Las cadenas largas de llamadas aumentan el riesgo de IDs confusos y parámetros incorrectos.
• Los errores sin explicación del siguiente paso dejan el modelo atrapado.
• Las respuestas demasiado voluminosas consumen rápidamente el contexto y rompen el diálogo.

Cómo diseñar herramientas

La conclusión del autor es dura pero útil: una herramienta MCP debe diseñarse no como un reflejo de la estructura de la base de datos, sino como una acción comprensible para el usuario. Si un humano necesita "asignar una tarea a Iván para mañana", la herramienta debe poder aceptar un nombre, fecha límite y texto de la tarea, en lugar de obligar al modelo a buscar por separado user_id, luego task_id y luego vincular entidades. Cuanto más autosuficiente sea la herramienta, mayor será la probabilidad de que el modelo ejecute el escenario sin fallos y sin orquestación casera dentro del prompt.

"Las herramientas deben reflejar la intención del usuario, no la

estructura de su base de datos."

La segunda parte del diseño es el texto. Para un modelo, la descripción de una herramienta, su nombre y los campos del esquema de entrada reemplazan efectivamente la interfaz. No ve README, no conoce la arquitectura y no entiende las intenciones del autor fuera del esquema JSON. Por lo tanto, las formulaciones deben ser semánticamente densas: cortas pero precisas. La diferencia entre `search_users`, `find_users` y `lookup_user_by_email` para LLM no es cosmética sino comportamental. Lo mismo se aplica a los errores: un buen mensaje de error no solo informa de una falla, sino que sugiere por qué sucedió y qué intentar después.

Pruebas y protección

Las pruebas unitarias clásicas son necesarias aquí, pero no son suficientes. Verifican el código de la herramienta, no cómo exactamente el modelo la seleccionará y la llamará. Por lo tanto, el artículo recomienda evals: conjuntos de solicitudes del usuario que permiten ver qué herramienta fue invocada, con qué parámetros y cuánto la respuesta coincide con el escenario. El problema es que el comportamiento de los modelos es inestable y cambia incluso entre versiones adyacentes. Lo que funcionó en una versión de GPT o Claude puede comportarse de manera diferente después de una actualización, por lo que las pruebas manuales en chat siguen siendo una parte obligatoria del desarrollo por ahora.

Una sección separada se dedica a la seguridad. MCP expande la superficie de ataque desde dos lados a la vez: a través del usuario con inyección de prompt y a través de los datos que el servidor mismo o sistemas externos devuelven. Si una herramienta tiene privilegios adicionales, el modelo tarde o temprano intentará hacer más de lo que debería. La receta práctica es esta: privilegios mínimos, filtrado de contenido externo, confirmación explícita para acciones irreversibles y limitación del tamaño de la respuesta. El autor recomienda devolver solo los campos necesarios, un máximo de 10-20 registros a la vez, y siempre recordar que incluso un modelo poderoso deja de ser útil cuando su contexto está lleno de JSON crudo.

Lo que esto significa

Los servidores MCP se están moviendo rápidamente de experimentos a producción, y con ello, el costo de los errores en el diseño de herramientas está creciendo. Los equipos ganadores no serán aquellos con más métodos de API, sino aquellos que saben cómo construir acciones cortas, comprensibles y seguras para el modelo, y luego verificarlas constantemente en escenarios reales.