Prompts: Reusable, High-Quality Workflows
What a Prompt Is
Prompts are the third server primitive: reusable, parameterized templates that package expert instructions for a common task. Instead of every user inventing their own wording for 'reformat this document as markdown', the server author writes one carefully tested prompt, and users invoke it on demand. Prompts let an MCP server ship not just capabilities, but know-how.
Prompts are USER-controlled
This completes the trio. Prompts are triggered by an explicit user action — a slash command, a button, a menu pick — not automatically by the model and not silently by the app. In Claude's interface, the workflow buttons under the chat box are prompts: the user decides to run them.
| Prompt method | Purpose | Returns |
|---|---|---|
| prompts/list | Discover available prompts | Array of prompt descriptors with arguments |
| prompts/get | Retrieve a filled-in prompt | The full message(s), with arguments interpolated |
prompts/get is where the template's parameters get substituted into real messages for the model.
Why Provide Prompts At All?
A fair question: users can already ask Claude to do most things directly. The value of a prompt is quality and consistency. As the server author, you can spend time crafting, testing, and refining a prompt that handles edge cases and follows best practices — then every user benefits from that expertise without becoming a prompt engineer. A well-built prompt produces reliable results every time, instead of varying with each user's phrasing.
- •Consistency — users get reliable output every time, regardless of how they'd have phrased it.
- •Expertise — you encode domain knowledge and edge-case handling into the template.
- •Reusability — multiple client applications can share the same prompt.
- •Maintenance — improve the prompt in one place and every client gets the upgrade.
Defining a Prompt with the SDK
Prompts use the same decorator pattern as tools and resources. The function returns a list of messages that get sent to Claude, with the user's arguments interpolated. Here's a format command: users type /format and a document ID, and Claude receives a thoroughly engineered instruction to reformat that document as markdown.
from mcp.server.fastmcp.prompts import base
from pydantic import Field
@mcp.prompt(
name="format",
description="Rewrites the contents of the document in Markdown format."
)
def format_document(
doc_id: str = Field(description="Id of the document to format")
) -> list[base.Message]:
prompt = f"""
Your goal is to reformat a document to be written with markdown syntax.
The id of the document you need to reformat is:
<document_id>
{doc_id}
</document_id>
Add in headers, bullet points, tables, etc. as necessary. Feel free to add structure.
Use the 'edit_document' tool to edit the document.
"""
return [base.UserMessage(prompt)]Prompts can orchestrate tools
Notice the prompt tells Claude to use the edit_document tool. Prompts often tie the other primitives together — a single user-triggered workflow that reads resources and calls tools in a tested, repeatable way.
How Users Trigger Prompts
Because prompts are user-controlled, applications surface them through explicit UI: slash commands (type '/' to see /format, /summarize), command palettes, dedicated buttons, or context menus. Like templated resources, prompt arguments support completion to help users supply valid values. When the user picks a prompt and fills its arguments, the client calls prompts/get, the server interpolates the values, and the resulting messages go to Claude.
A user-triggered prompt flows from a slash command to prompts/get to interpolated messages for Claude.
Next
You've met all three primitives. The next lesson gives you a crisp decision rule for choosing tools vs resources vs prompts — a favorite exam topic.
Key Takeaways
- ✓Prompts are the third primitive: reusable, parameterized instruction templates that package tested expertise for a common task.
- ✓Prompts are USER-controlled — triggered explicitly via slash commands, buttons, or menus (e.g. Claude's workflow buttons), not by the model or silently by the app.
- ✓Methods: prompts/list (discover) and prompts/get (retrieve with arguments interpolated into real messages).
- ✓Value: consistency, encoded expertise, cross-client reusability, and one-place maintenance — users get great results without being prompt engineers.
- ✓With the SDK, @mcp.prompt() decorates a function that returns a list of messages (base.UserMessage/AssistantMessage); arguments are interpolated at prompts/get time.
- ✓Prompts often orchestrate the other primitives — a single tested workflow that reads resources and calls tools.
Check Your Understanding
Test what you learned in this lesson.
Q1.Prompts in MCP are controlled by whom?
Q2.What is the main reason to ship a prompt instead of letting users phrase requests themselves?
Q3.With the Python SDK, what does a function decorated with @mcp.prompt() return?
Q4.Which protocol operation interpolates a prompt's arguments into actual messages?
Practice This Lesson