TopolearnPrompts package your team's best instructions so every user starts a task the same, well-tested way.
A prompt is a template a user invokes, usually as a slash command or menu item in the host. The host calls prompts/get with the arguments the user filled in, and the server returns one or more messages to put into the conversation.
In the Python SDK, decorate a function with @mcp.prompt():
- Its name, docstring and parameters become the prompt's name, description and arguments.
- Return a string and it becomes a single user message.
- Return a list of messages (
UserMessage,AssistantMessage) to set up a multi-turn start, for example a canned assistant reply that asks a follow-up question. - Use
Annotated[str, Field(description=...)]so the host can show helpful hints next to each argument, and defaults for optional ones.
Good uses: a code-review checklist, an incident-report template, "explain this SQL". The value is consistency: the instructions are written once on the server instead of retyped by every user.
Prompts don't run anything; they only produce messages. If a template needs live data, the host can attach resources alongside it, or the prompt text can tell the model which tool to call first.
The server can also offer completions (argument autocomplete) for prompt and template arguments, so the host can suggest valid values while the user types.
Example
from typing import Annotated
from pydantic import Field
from mcp.server import MCPServer
from mcp.server.mcpserver.prompts.base import AssistantMessage, UserMessage
mcp = MCPServer("Code Helper")
@mcp.prompt(title="Code review")
def review_code(
code: Annotated[str, Field(description="The code to review")],
language: str = "python",
) -> str:
"""Review code for bugs, readability and tests."""
return f"Review this {language} code. List bugs first, then style issues:\n\n{code}"
@mcp.prompt()
def debug_error(error: str) -> list:
"""Start a debugging conversation about an error message."""
return [
UserMessage(f"I'm seeing this error:\n{error}"),
AssistantMessage("Let's debug it. What changed right before it started?"),
]Remember
- Prompts are user-invoked templates returned by prompts/get
- Return a string (one user message) or a list of messages
- Describe arguments with Field so hosts can show hints
- Prompts produce messages; they don't execute anything