Los servidores MCP (Model Context Protocol) se han convertido en la forma estandar de dar herramientas a los agentes de IA. Pero un MCP mal definido satura el contexto del modelo, provoca llamadas erroneas y encarece cada interaccion. Estas son las buenas practicas que aplicamos en CloudAPPI para disenar MCPs que los LLM usan de forma fiable.
1. Número de herramientas y granularidad
Menos es mas. Manten entre 1 y 10 herramientas activas por servidor. Si una herramienta admite varias operaciones similares, consolidalas en un unico tool con un parametro action de tipo enum, en lugar de crear una herramienta por operacion. Cuando el catalogo supera las 20 herramientas, expon un mecanismo de descubrimiento progresivo (por ejemplo un search_tools) para que el agente cargue solo lo que necesita.
2. Descripciones de las herramientas
La descripcion es el prompt que el modelo lee para decidir. Escribela en texto plano o Markdown, no en JSON. Indica con claridad cuando usar la herramienta y, sobre todo, cuando NO usarla. Reserva el JSON Schema exclusivamente para inputSchema y outputSchema.
3. Diseño de esquemas y parámetros
- Usa enums estrictos siempre que el conjunto de valores sea cerrado.
- Define valores por defecto sensatos.
- Emplea nombres claros y orientados al usuario.
- Limita cada herramienta a menos de 8 parametros.
- Incluye ejemplos de entrada en la descripcion.
4. Campos no enumerables
Cuando un parametro no puede cerrarse en un enum (por ejemplo, un identificador de proyecto), incluye los valores mas frecuentes en la descripcion y ofrece un metodo complementario que devuelva la lista completa, de modo que el agente resuelva el valor correcto sin adivinar.
5. Payloads y mensajes de error
Devuelve solo datos de alto valor: cada token cuenta. Usa JSON para datos estructurados y Markdown para resumenes legibles. Los mensajes de error deben ser accionables: en lugar de un escueto 400, explica que parametro fallo y como corregirlo.
6. Conoce los limites del consumidor
Los principales LLM (OpenAI, Anthropic, Gemini) rinden mejor con 10-20 herramientas activas. Ten en cuenta la rigidez de cada esquema y una gestion de contexto cuidadosa: un MCP que ignora estos limites degrada la precision del agente.
En resumen
Un buen MCP es pequeno, explicito y predecible: pocas herramientas bien descritas, esquemas estrictos, payloads minimos y errores accionables. Asi conseguimos agentes mas fiables y mas baratos de operar.
En CloudAPPI ayudamos a las organizaciones a disenar, gobernar y exponer sus MCP y API para la era de los agentes de IA.
