Mejores Prácticas para Conceptos Centrales de MCP

Diseñar un servidor MCP de manera efectiva significa que cada herramienta, recurso y prompt sea predecible para los clientes y modelos que lo utilizan, no solo funcional en tus propias pruebas.

Esta lista de verificación recopila las prácticas que vale la pena seguir en esquemas de herramientas, URIs de recursos, plantillas de prompts y cómo implementas el servidor en sí.

Cómo Usar Esta Lista de Verificación

• Recorre cada grupo con letras al diseñar un nuevo servidor, o al revisar uno existente antes de compartirlo más ampliamente.
• Trata el grupo de diseño de herramientas como la máxima prioridad, ya que la mayoría de los servidores comienzan allí y la mayoría de los problemas de selección de modelos se remontan a esquemas de herramientas poco claros.
• Vuelve a visitar el grupo de implementación cada vez que un servidor pase de un prototipo local a algo compartido con un equipo o expuesto de forma remota.

A - Diseño de Herramientas

• Nombra las herramientas comenzando con un verbo, describiendo la acción claramente. create_task se lee como una acción; task o handle no le dan al modelo nada con qué coincidir la intención.
• Escribe una docstring de una línea más un bloque Args: para cada herramienta. La docstring es el texto principal que el modelo utiliza para juzgar la relevancia, y las notas por argumento aclaran las unidades y formatos que una pista de tipo por sí sola no puede expresar.
• Mantén cada herramienta con un alcance limitado a una sola tarea. Una herramienta con un indicador mode o action oculta múltiples comportamientos detrás de un solo esquema y hace que la selección del modelo sea menos confiable.
• Usa pistas de tipo, Literal, o modelos Pydantic para validar las entradas antes de que se ejecute tu manejador. Esto detecta argumentos incorrectos como un error de esquema en lugar de un fallo en tiempo de ejecución dentro de tu código.
• Lanza excepciones con mensajes específicos en caso de fallo, nunca devuelvas None o una cadena vacía. Un fallo silencioso no le da al modelo ninguna señal de que algo salió mal.
• Evita el estado mutable compartido sin protección entre llamadas concurrentes a herramientas. Las condiciones de carrera en variables globales en memoria corrompen los datos bajo uso real; respalda el estado compartido con un almacén de datos real.

B - Diseño de Recursos

• Mantén los recursos estrictamente de solo lectura. Cualquier cosa que cree, actualice o elimine datos pertenece a una herramienta, no a un recurso, para que los clientes puedan almacenar en caché o volver a leer de forma segura el contenido del recurso.
• Elige un esquema de URI claro y consistente por tipo de entidad. Un esquema como articles://{id} o docs://{filename} hace que los recursos sean predecibles de descubrir y razonar sobre ellos.
• Protege cualquier recurso basado en el sistema de archivos contra la traversa de directorios. Resuelve la ruta y confirma que permanece dentro del directorio raíz previsto antes de leer, ya que un parámetro de nombre de archivo sin procesar puede escapar del directorio servido.
• Devuelve contenido estructurado, como JSON, para cualquier cosa con más de un campo. El texto plano no estructurado obliga a cada cliente a escribir análisis ad hoc.
• Lanza una excepción clara cuando un recurso solicitado genuinamente no existe. Un valor de retorno vacío oculta la diferencia entre "sin datos" y "ocurrió un error".

C - Diseño de Prompts

• Utiliza un Prompt solo cuando la consistencia en la redacción entre múltiples clientes sea el problema real. Un prompt utilizado por un solo cliente agrega sobrecarga de diseño sin el beneficio para el que existe.
• Parametriza los prompts con argumentos tipados en lugar de codificar datos variables. Esto evita duplicar una función de prompt completa para cada pequeña variante.
• Inicia los prompts de múltiples mensajes con una guía de enmarcado explícita antes de la solicitud del usuario. Un mensaje de instrucción claro le da a cada cliente una estructura consistente que esperar.
• Trata la redacción del prompt como un activo mantenido, no como un artefacto que se escribe una vez. Dado que un prompt está centralizado, un prompt no ajustado afecta a cada cliente que lo utiliza; itera basándote en la calidad de la salida real.
• Nunca codifiques datos sensibles o variables directamente en la fuente de una plantilla de prompt. Pásalos como un argumento en el momento de la llamada en su lugar, la misma disciplina aplicada a cualquier código del lado del servidor.

D - Selección de Primitivas

• Pregunta si una operación cambia algo antes de elegir una primitiva. Si es así, es una Herramienta; si es una lectura pura, considera primero un Recurso; si empaqueta instrucciones reutilizables, es un Prompt.
• Evita hacer de todo una Herramienta por conveniencia. Enterrar lecturas seguras y almacenables en caché dentro de la misma primitiva que las acciones destructivas hace que un servidor sea más difícil de razonar y más fácil de malinterpretar.
• Empareja Herramientas y Recursos deliberadamente cuando un flujo de trabajo necesite ambos. Una herramienta que crea un registro y un recurso que lo expone para lectura posterior es una combinación común y limpia.

E - Transporte e Implementación

• Por defecto, usa stdio para herramientas locales de un solo desarrollador. No necesita configuración de red, TLS ni autenticación, y su ciclo de vida está ligado limpiamente al cliente que lo lanzó.
• Pasa a HTTP/SSE solo cuando un servidor necesite genuinamente servir a múltiples clientes o persistir de forma independiente. Agregar complejidad de red sin esa necesidad es una sobrecarga innecesaria.
• Nunca vincules un servidor remoto a una interfaz pública sin autenticación. Ponlo detrás de un proxy inverso con TLS y una capa de autenticación, o restringe su acceso a una interfaz privada, antes de que sea accesible más allá de una red confiable.
• Considera un túnel MCP cuando un servidor deba permanecer dentro de una red privada pero aún necesite accesibilidad remota. Esto puede evitar la carga operativa de abrir puertos de entrada y configurar un punto final TLS público, aunque sigue siendo una vista previa de investigación a partir de 2026, por lo que verifica la guía actual antes de depender de él.
• Escribe manejadores para que sean seguros bajo llamadas concurrentes una vez que un servidor sirva a más de un cliente. Un servidor remoto y compartido ve solicitudes superpuestas de una manera que un proceso stdio de un solo cliente nunca lo hace.

Aplicando Esta Lista de Verificación en Orden

• Comienza con A y B (1-2): las decisiones de diseño de herramientas y recursos dan forma a todo lo que sigue, incluida la fiabilidad con la que el modelo selecciona la capacidad correcta.
• Agrega C solo cuando sea necesario: los prompts son valiosos, pero omitirlos para un servidor con un solo cliente es una opción razonable y deliberada.
• Termina con D y E antes de compartir ampliamente: la selección de primitivas y la disciplina de implementación son lo más importante una vez que más de una persona o cliente depende del servidor.

Preguntas Frecuentes

Relacionados

• Entendiendo MCP: Herramientas, Recursos y Prompts - la base conceptual que asume esta lista de verificación.
• Definición de Herramientas Llamables en un Servidor MCP - el detalle completo detrás del grupo de diseño de herramientas.
• Exposición de Datos Legibles como Recursos MCP - el detalle completo detrás del grupo de diseño de recursos.
• Creación de Plantillas de Prompts Reutilizables con Prompts MCP - el detalle completo detrás del grupo de diseño de prompts.
• Elección entre Transportes stdio y HTTP/SSE para MCP - el detalle completo detrás del grupo de transporte e implementación.
• Referencia de Túneles MCP para Acceso a Red Privada - la opción de vista previa de investigación mencionada en el grupo de implementación.

Versiones de Stack: Escrito contra la línea de modelos Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado), y Claude Haiku 4.5 - y la especificación actual del Protocolo de Contexto del Modelo. Los nombres de los modelos, las versiones del SDK y la especificación MCP se mueven rápidamente; verifica los detalles actuales en platform.claude.com/docs y modelcontextprotocol.io antes de confiar en ellos.