Defining MCP Prompts as Reusable Templates

Prompts in MCP servers let you define pre-built, high-quality instructions that clients can use instead of writing their own prompts from scratch. Think of them as carefully crafted templates that give better results than what users might come up with on their own. Users can already ask Claude to do most tasks directly, but they will get much better results if you provide a thoroughly tested, specialized prompt that handles edge cases and follows best practices. As the MCP server author, you can spend time crafting and evaluating prompts that work consistently. Users benefit from your expertise without having to become prompt engineering experts themselves.

A practical example is a format command that converts documents to markdown. The user-facing workflow looks like this: the user types a slash to see the available commands, selects format, and specifies a document ID. The client then asks the MCP server for the format prompt with that document ID as an argument. The server fills the document ID into the prompt template and returns the resulting messages. The client sends those messages to Claude. Claude reads and reformats the document using the available tools. The user gets back clean markdown with proper headers, lists, and formatting, all from a single slash command.

Prompts use a similar decorator pattern to tools and resources. You write a Python function that builds a prompt for some task, accepting whatever arguments make sense, like a document ID. You apply the mcp prompt decorator to register that function with the server. Inside the function, you construct a list of messages, typically alternating user and assistant roles, that fully describe the task you want the model to perform. The function returns that list of messages. When a client requests the prompt with arguments, the SDK calls your function and returns the resulting messages directly to the client.

You use the MCP Inspector to test your prompts before deploying them. In the Prompts section, you can see every prompt your server exposes. When you select a prompt, the Inspector shows you the arguments it expects. You fill in test values, run the prompt, and see exactly what messages will be sent to the model, including how variables get interpolated into your prompt template. This lets you verify the prompt looks correct, that variable substitution works, and that the structure of the messages is what you intended, all before any real user starts relying on it.

Prompts give you four big benefits. Consistency, because users get reliable results every time they invoke the same prompt. Expertise, because you can encode domain knowledge and prompt engineering best practices directly into the prompt itself. Reusability, because multiple client applications can use the same prompts from a single shared server. And maintenance, because you can update prompts in one place and immediately improve every client that uses them. Prompts work best when they are specialized for your MCP server's domain. A document server has prompts for formatting, summarizing, or analyzing documents. A data analysis server has prompts for generating reports.