Crea prompts reutilizables que estructuran cómo interactúa el modelo con tu servidor.
En el contexto de MCP, los prompts son plantillas de instrucciones que el server ofrece al modelo. Son distintos de las tools (que ejecutan acciones) y los resources (que proporcionan datos). Los prompts estructuran como el modelo debe pensar y responder en escenarios específicos usando el decorator @mcp.prompt() para registrarlos en el servidor.
Un prompt MCP es una plantilla reutilizable que define instrucciones para el modelo. Mientras que las herramientas ejecutan acciones concretas (buscar datos, enviar mensajes) y los recursos exponen datos estáticos (archivos, configuraciones), los prompts definen patrones de interacción — cómo debe analizar el modelo el código, generar informes o dar formato a las respuestas. El decorator @mcp.prompt() registra una función de Python como un prompt disponible en el server, que el client puede enumerar e invocar.
Piensa en los prompts como recetas predefinidas para el modelo. En vez de que el usuario escriba "analiza este código centrándote en los errores, el rendimiento y la legibilidad" cada vez, el servidor ofrece un prompt "revisar_codigo" listo para usar. El cliente elige el prompt, el servidor devuelve las instrucciones con formato y el modelo sabe exactamente qué hacer. Es reutilización del conocimiento en forma de instrucciones.
El prompt más básico es una función decorada con @mcp.prompt() que devuelve una cadena. Esta cadena contiene las instrucciones que se enviarán al modelo. Sencillo, directo y potente: basta con definir la función y MCP se encarga del resto.
Crear un prompt simple solo requiere el decorador y una función que devuelva una cadena:
El nombre de la función (revisar_codigo) se convierte en el identificador del prompt. La docstring se convierte en la descripción. La cadena devuelta se convierte en el contenido del prompt que se envía al modelo.
Los prompts estáticos son útiles, pero su verdadero potencial aparece cuando agregas parámetros dinámicos. Al usar type hints de Python, MCP detecta automáticamente los parámetros y los expone al client, que puede completarlos antes de invocar el prompt.
Los parámetros se definen como argumentos de la función con type hints:
MCP usa los type hints para indicar al client qué parámetros se esperan. El client presenta campos para que el usuario los complete (ej.: tipo="ventas", periodo="Q1 2025") antes de invocar el prompt.
Usa nombres descriptivos para los parámetros — tipo e periodo son mejores que t e p. El client muestra estos nombres al usuario, así que la claridad importa. Si un parámetro es opcional, usa Optional[str] = None como anotación de tipo.
El cliente enumera los prompts disponibles y ve "gerar_relatorio" con parámetros tipo (str) y periodo (str).
El usuario completa los parámetros: tipo="ventas", periodo="marzo 2025".
El server ejecuta la función, sustituye los parámetros en la string y devuelve el prompt completo al modelo.
El client MCP puede solicitar la lista de todos los prompts disponibles en el server, incluidos sus nombres, descripciones y parámetros. Esto permite que las interfaces de usuario muestren un catálogo de prompts disponibles y que la experiencia sea intuitiva y esté autodocumentada.
El protocolo MCP define el método prompts/list que devuelve todos los prompts registrados en el server. Para cada prompt, el client recibe: el nombre (derivado del nombre de la función), la descripción (derivada del docstring de la función) y la lista de parámetros (derivada de los type hints). Esto significa que la documentación del prompt se genera automáticamente a partir del código Python; no es necesario mantener documentación aparte.
Qué recibe el client al listar prompts:
Los prompts MCP destacan cuando tienes patrones de interacción que se repiten con frecuencia. En vez de que cada usuario escriba sus propias instrucciones (muchas veces de forma incoherente), el server ofrece prompts estandarizados y probados que garantizan resultados de alta calidad.
Los mejores prompts MCP encapsulan experiencia en el dominio en plantillas reutilizables. Un prompt para analizar código puede incluir criterios que usaría un desarrollador sénior. Un prompt para informes puede seguir el formato oficial de la empresa. La idea es transformar el conocimiento tácito en instrucciones explícitas y compartibles, para que cualquier usuario obtenga resultados de nivel experto.
Prompt que indica al modelo que revise el código centrándose en errores, seguridad, rendimiento y legibilidad, con una lista de verificación estandarizada del equipo.
Prompt parametrizado que genera informes en un formato específico con métricas, gráficos sugeridos y recomendaciones prácticas.
Prompt que transforma datos sin procesar en tablas con formato, JSON estructurado o CSV, con reglas de validación integradas.
Prompt que genera correos electrónicos profesionales siguiendo el tono y el formato de la empresa, con parámetros para el destinatario, el asunto y el contexto.
Prompt que analiza documentación técnica y verifica su claridad, exhaustividad, ejemplos y coherencia con los estándares del proyecto.
Antes de poner prompts a disposición para su uso en producción, es esencial probarlos. MCP Inspector permite listar todos los prompts del server, ver los parámetros esperados e invocar prompts manualmente para verificar que las instrucciones generadas sean correctas y completas.
O MCP Inspector es la herramienta ideal para probar prompts. En la pestaña «Prompts», muestra todos los prompts registrados con sus nombres, descripciones y parámetros. Puedes completar los parámetros y hacer clic en «Get Prompt» para ver exactamente qué se enviará al modelo. Esto permite validar que las instrucciones estén completas, que los parámetros se sustituyan correctamente y que el formato sea adecuado, todo sin necesidad de conectarse a Claude Desktop.
Prueba cada prompt con valores extremos: cadenas vacías, textos muy largos, caracteres especiales. Verifica que el prompt gestione bien los casos límite. Si un parámetro es opcional, pruébalo con y sin él. Si el prompt usa f-strings, confirma que la interpolación funcione correctamente en todos los escenarios previstos.
Los prompts no validan los parámetros automáticamente: si el client envía una cadena vacía para un parámetro obligatorio, el prompt se generará con ese espacio en blanco. Siempre valida los parámetros dentro de la función antes de construir la cadena de retorno. Usa if not tipo: raise ValueError("tipo é obrigatório") para garantizar que los datos no válidos no pasen inadvertidos.
@mcp.prompt() — diferentes de tools y resources.
Siguiente Módulo: 3.8 — Manejo de errores