Skip to main content

Defining prompts

📖 Lesson content

Summary

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.

Why Use Prompts?

Let's say you want Claude to reformat a document into markdown. A user could just type "convert report.pdf to markdown" and get decent results. But they'd probably get much better output if they used a thoroughly tested, specialized prompt that you've designed specifically for document formatting.

The key insight is that while users can accomplish these tasks on their own, they'll get superior results when using prompts that have been carefully engineered and tested by the MCP server authors.

How Prompts Work

Prompts define a set of user and assistant messages that clients can use directly. When a client requests a prompt, your server returns a list of messages that can be sent straight to Claude.

The basic structure looks like this:

@mcp.prompt(
    name="format",
    description="Rewrites the contents of a document in Markdown format",
)
def format_document(
    doc_id: str = Field(description="Id of the document to format"),
) -> list[base.Message]:
    # Return a list of messages

Building a Format Command

Here's a practical example. We'll create a format command that lets users type /format doc_id to reformat any document into markdown syntax.

The prompt implementation includes detailed instructions for Claude:

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:

{doc_id}

Add in headers, bullet points, tables, etc as necessary. Feel free to add in structure.
Use the 'edit_document' tool to edit the document. After the document has been reformatted...
"""
    
    return [
        base.UserMessage(prompt)
    ]

Testing Your Prompts

You can test prompts using the MCP Inspector. Navigate to the Prompts tab, select your prompt, and provide any required parameters.

The inspector shows you exactly what messages will be sent to Claude, including how any parameters get interpolated into the prompt text.

Key Benefits

  • Quality control - You can test and refine prompts before users see them
  • Consistency - Users get reliable results every time
  • Specialization - Prompts can be tailored to your server's specific domain
  • Reusability - Multiple clients can use the same well-crafted prompts

Implementation Details

Don't forget to import the base module for message types:

from mcp.server.fastmcp import FastMCP
from mcp.server.fastmcp.prompts import base

Prompts should be high quality, well-tested, and relevant to your MCP server's overall purpose. In our document management example, formatting prompts make perfect sense since the server specializes in document operations.

🔁 Related lessons

📚 Source & attribution

Was this lesson helpful?

Feedback / ReportSpotted an issue or have an improvement idea?