Prompts

Un prompt es una plantilla de mensajes que elige el usuario.

Las herramientas son para el modelo. Un prompt es lo contrario: el usuario elige uno en un menú de su cliente (un comando de barra, un botón), completa sus argumentos y los mensajes renderizados entran en la conversación como si los hubiera escrito él mismo.

Para declarar uno, pon @mcp.prompt() en una función que devuelva el texto.

Tu primer prompt

from mcp.server import MCPServer

mcp = MCPServer("Code Helper")


@mcp.prompt()
def review_code(code: str) -> str:
    """Review a piece of code."""
    return f"Please review this code:\n\n{code}"

El SDK lee las mismas tres cosas que lee de una herramienta:

• El nombre es el nombre de la función: review_code.
• La descripción que muestra el cliente es el docstring: Review a piece of code.
• Los argumentos salen de los parámetros. code no tiene valor por defecto, así que es obligatorio.

Esto es lo que recibe un cliente de prompts/list:

{
  "name": "review_code",
  "description": "Review a piece of code.",
  "arguments": [
    {"name": "code", "required": true}
  ]
}

Aquí no hay JSON Schema. Los argumentos de un prompt son una lista plana de valores de cadena con nombre: un formulario que rellena una persona, no un payload que construye un modelo.

Renderizarlo

El cliente renderiza la plantilla con prompts/get, pasando los argumentos. Tu función se ejecuta y el str que devuelves se convierte en un único mensaje de usuario:

{
  "description": "Review a piece of code.",
  "messages": [
    {
      "role": "user",
      "content": {
        "type": "text",
        "text": "Please review this code:\n\ndef add(a, b): return a + b"
      }
    }
  ],
  "resultType": "complete"
}

Esa es toda la vida de un prompt: se lista por nombre, se renderiza a demanda y se coloca en el chat.

mcp.shared.exceptions.MCPError: Internal server error

Pruébalo

Ejecuta el servidor con el MCP Inspector:

uv run mcp dev server.py

Abre la pestaña Prompts y selecciona review_code. El Inspector dibuja un formulario con un campo obligatorio code. Rellénalo, renderízalo y te devuelve exactamente el mensaje de usuario de arriba.

Más de un mensaje

Una revisión de código es un mensaje. Una sesión de depuración es una conversación, y un prompt puede sembrarla entera.

Devuelve una lista de mensajes en lugar de un str:

from mcp.server import MCPServer
from mcp.server.mcpserver.prompts.base import AssistantMessage, Message, UserMessage

mcp = MCPServer("Code Helper")


@mcp.prompt()
def review_code(code: str) -> str:
    """Review a piece of code."""
    return f"Please review this code:\n\n{code}"


@mcp.prompt()
def debug_error(error: str) -> list[Message]:
    """Start a debugging conversation."""
    return [
        UserMessage("I'm seeing this error:"),
        UserMessage(error),
        AssistantMessage("I'll help debug that. What have you tried so far?"),
    ]

• UserMessage y AssistantMessage vienen de mcp.server.mcpserver.prompts.base. Dales un str y lo envuelven en TextContent por ti. El rol es el nombre de la clase.
• Message es su base común. Úsala como anotación de retorno.

Renderizar debug_error ahora produce tres mensajes, en orden:

{
  "description": "Start a debugging conversation.",
  "messages": [
    {"role": "user", "content": {"type": "text", "text": "I'm seeing this error:"}},
    {"role": "user", "content": {"type": "text", "text": "TypeError: 'int' object is not iterable"}},
    {
      "role": "assistant",
      "content": {"type": "text", "text": "I'll help debug that. What have you tried so far?"}
    }
  ],
  "resultType": "complete"
}

Fíjate en el último. Rellenar de antemano un turno assistant es la forma de orientar la siguiente respuesta del modelo sin que el usuario tenga que escribir esa orientación.

Títulos y descripciones de argumentos

review_code es un nombre de función, no una etiqueta. Dale al cliente algo mejor que poner en el botón y describe cada argumento para que el formulario se explique solo:

from typing import Annotated

from pydantic import Field

from mcp.server import MCPServer

mcp = MCPServer("Code Helper")


@mcp.prompt(title="Code review")
def review_code(
    code: Annotated[str, Field(description="The code to review.")],
    language: Annotated[str, Field(description="The language the code is written in.")] = "python",
) -> str:
    """Review a piece of code."""
    return f"Please review this {language} code:\n\n{code}"

• title="Code review" es el nombre legible para personas, exactamente igual que el title de una herramienta.
• Annotated[str, Field(description=...)] es el mismo patrón que usa Herramientas para describir los parámetros de una herramienta. Aquí la descripción va al argumento en lugar de a un esquema.
• language tiene valor por defecto, así que deja de ser obligatorio.

La entrada de prompts/list ahora lleva todo lo que un cliente necesita para dibujar un buen formulario:

{
  "name": "review_code",
  "title": "Code review",
  "description": "Review a piece of code.",
  "arguments": [
    {"name": "code", "description": "The code to review.", "required": true},
    {"name": "language", "description": "The language the code is written in.", "required": false}
  ]
}

Resumen

• @mcp.prompt() en una función la convierte en un prompt. El nombre sale de la función y la descripción del docstring.
• Los prompts están controlados por el usuario: el cliente los lista, el usuario elige uno y completa los argumentos.
• Los argumentos son una lista plana de cadenas con nombre (sin esquema). Un parámetro con valor por defecto es opcional.
• Devuelve un str y se convierte en un mensaje de usuario. Devuelve una lista de UserMessage / AssistantMessage para sembrar una conversación de varios turnos.
• title= y Field(description=...) son lo que un cliente pone en su interfaz.
• Un argumento obligatorio que falta hace fallar toda la solicitud. No hay un resultado de error por prompt.

El autocompletado en el servidor de los argumentos de un prompt (o de una plantilla de recurso) está en Autocompletado.