Bitrix24 enumera ocho errores típicos al desarrollar servidores MCP para LLM

Un desarrollador del equipo de IA de Bitrix24 ha publicado un análisis práctico de los errores que con más frecuencia rompen los servidores MCP para LLM. La idea central es sencilla: MCP parece un envoltorio determinista sobre una API, pero quien controla esa capa es un modelo no determinista. Por eso los enfoques de ingeniería habituales fallan aquí con regularidad.

Dónde se rompe todo

El primer problema es la autorización. En la especificación todo parece ordenado: hay OAuth, campos claros y un flujo previsible. En la práctica, los distintos clientes MCP lo implementan de forma desigual. En unos la autorización funciona parcialmente, en otros con extensiones propias y en algunos casi no funciona. Para los servidores stdio locales esto no es tan crítico, pero en cuanto el servidor sale a la red empieza la fragmentación. Por eso los equipos suelen acabar en una opción menos elegante pero estable: tokens emitidos de antemano que el usuario añade a mano en la configuración.

La segunda gran trampa es la tentación de envolver un Swagger en MCP tal cual. Para el desarrollador tiene lógica: cada endpoint de la API se convierte en una herramienta. Para el modelo, es una trampa de elección. Cuando tiene decenas de herramientas parecidas, empieza a confundir escenarios, elige mal los comandos y se equivoca en los parámetros. La situación empeora cuando hay que recorrer una cadena larga de acciones: buscar al usuario, recordar su ID, crear una tarea y después añadir un observador. Una persona lo resuelve, pero el modelo puede perder el estado fácilmente a mitad del recorrido.

• Los clientes implementan la autorización de forma distinta, así que un mismo servidor se comporta de manera impredecible.
• Un conjunto amplio de herramientas reduce la probabilidad de que el modelo elija la correcta.
• Las cadenas de llamadas largas aumentan el riesgo de confundir IDs y usar parámetros incorrectos.
• Los errores que no explican el siguiente paso dejan al modelo en un callejón sin salida.
• Las respuestas demasiado voluminosas consumen rápido el contexto y rompen el diálogo.

Cómo diseñar las herramientas

La conclusión del autor es tajante, pero útil: una herramienta MCP no debe diseñarse como reflejo de la estructura de la base de datos, sino como una acción comprensible para el usuario. Si alguien necesita «asignar una tarea a Iván para mañana», la herramienta debe aceptar el nombre, el plazo y el texto de la tarea, en lugar de obligar al modelo a buscar por separado el user_id, luego el task_id y después vincular las entidades. Cuanto más autosuficiente sea la herramienta, más probable es que el modelo complete el escenario sin fallos y sin una orquestación improvisada dentro del prompt.

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

estructura de tu base de datos».

La segunda parte del diseño son los textos. Para el modelo, la descripción de la herramienta, su nombre y los campos del esquema de entrada sustituyen en la práctica a la interfaz. No ve el README, no conoce la arquitectura y no entiende las intenciones del autor más allá del esquema JSON. Por eso las formulaciones deben ser semánticamente densas: breves, pero precisas. Para un LLM, la diferencia entre `search_users`, `find_users` y `lookup_user_by_email` no es cosmética: afecta a su comportamiento. Lo mismo ocurre con los errores: un buen mensaje de error informa del fallo y, además, indica por qué ha ocurrido y qué probar a continuación.

Tests y protección

Los tests unitarios clásicos son necesarios aquí, pero no suficientes. Comprueban el código de la herramienta, no cómo la elegirá y la invocará el modelo. Por eso el artículo recomienda evals: conjuntos de peticiones de usuario con los que observar qué herramienta se llamó, con qué parámetros y en qué medida la respuesta se ajusta al escenario. El problema es que el comportamiento de los modelos es inestable y cambia incluso entre versiones consecutivas. Lo que funcionaba en una versión de GPT o Claude puede empezar a comportarse de otra forma tras una actualización, así que las pruebas manuales en el chat siguen siendo, por ahora, una parte obligatoria del desarrollo.

Un bloque aparte está dedicado a la seguridad. MCP amplía la superficie de ataque por dos frentes a la vez: a través del usuario, con prompt injection, y a través de los datos que devuelve el propio servidor o los sistemas externos. Si una herramienta tiene permisos de más, tarde o temprano el modelo intentará hacer más de lo que debe.

La receta práctica es esta: mínimo privilegio, filtrado del contenido externo, confirmación explícita para las acciones irreversibles y límite al tamaño de las respuestas. El autor aconseja devolver solo los campos necesarios, un máximo de 10–20 registros cada vez, y recordar siempre que incluso un modelo potente deja de ser útil cuando su contexto está saturado de JSON en bruto.

Qué significa esto

Los servidores MCP están pasando rápidamente de los experimentos a producción, y con ello crece el coste de los errores en el diseño de herramientas. No ganarán los equipos con más métodos de API, sino los que sepan construir acciones cortas, claras y seguras para el modelo, y luego revisarlas constantemente con escenarios reales.