Prompts

Prompts are reusable message templates that help AI agents interact with your server effectively. They provide structured ways to guide conversations and standardize common interactions.

Example

@server.prompt(
    name="code_review",
    title="Code Review",
    description="Generate a code review prompt for a given language and focus area",
)
def code_review_prompt(language: str, focus: str = "general") -> str:
    """Generate a code review prompt."""
    focus_instructions = {
        "general": "for overall quality, readability, and best practices.",
        "security": "focusing on security vulnerabilities and potential exploits.",
        "performance": "focusing on performance optimizations and efficiency.",
    }
    instruction = focus_instructions.get(focus, focus_instructions["general"])
    return f"Please review the following {language} code {instruction}"

Anatomy of a Prompt

When a client calls prompts/list, the server returns metadata for each prompt including its arguments. Here’s the JSON-RPC response that the example above produces when a client calls prompts/list:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "prompts": [
      {
        "name": "code_review",
        "title": "Code Review",
        "description": "Generate a code review prompt for a given language and focus area",
        "arguments": [
          {
            "name": "language",
            "required": true
          },
          {
            "name": "focus",
            "required": false
          }
        ]
      }
    ]
  }
}

Here’s what maps to what:

Python	MCP Schema	Notes
`name="code_review"`	`"name"`	Falls back to function name if omitted
`title="Code Review"`	`"title"`	Human-readable display name
`description="Generate a code review..."`	`"description"`	Falls back to docstring if omitted
`language: str` (no default)	`{"name": "language", "required": true}`	Parameters without defaults are required
`focus: str = "general"`	`{"name": "focus", "required": false}`	Parameters with defaults are optional
`context: Context`	(not in schema)	Automatically excluded

Argument Descriptions

You can add descriptions to prompt arguments the same way as tools, using Annotated and Field:

from typing import Annotated
from pydantic import Field

@server.prompt(name="code_review")
def code_review_prompt(
    language: Annotated[str, Field(description="The programming language of the code")],
    focus: Annotated[str, Field(description="Review focus area", default="general")],
) -> str:
    """Generate a code review prompt."""
    return f"Please review the following {language} code for {focus}."

This adds description to each argument in the response:

{
  "arguments": [
    {
      "name": "language",
      "description": "The programming language of the code",
      "required": true
    },
    {
      "name": "focus",
      "description": "Review focus area",
      "required": false
    }
  ]
}

Minimal Definition

At minimum, a prompt only needs a function:

@server.prompt()
def greeting() -> str:
    """A friendly greeting prompt."""
    return "Hello! How can I help you today?"

The function name becomes the prompt name, and the docstring becomes the description.

Using Context

Access the MCP context for advanced features. Add a Context parameter - it’s automatically excluded from the prompt’s arguments:

from mcp_use.server import Context

@server.prompt(name="contextual")
async def contextual_prompt(context: Context) -> str:
    """A prompt that uses context information."""
    return "Based on the current context, please..."

Multi-Message Prompts

Return structured messages for complex prompts:

from mcp.types import PromptMessage, TextContent

@server.prompt(name="interview")
def interview_prompt(role: str) -> list[PromptMessage]:
    """Generate an interview prompt sequence."""
    return [
        PromptMessage(
            role="user",
            content=TextContent(
                type="text",
                text=f"I'm interviewing for a {role} position.",
            ),
        ),
        PromptMessage(
            role="assistant",
            content=TextContent(
                type="text",
                text=f"I'll help you prepare for your {role} interview. Let's start with common questions.",
            ),
        ),
    ]

Async Prompts

Prompts can be async for dynamic content generation:

@server.prompt(name="daily_brief")
async def daily_brief() -> str:
    """Generate a daily briefing prompt."""
    from datetime import datetime
    today = datetime.now().strftime("%A, %B %d")
    return f"Good morning! Today is {today}. What would you like to accomplish?"

Prompts vs Tools vs Resources

Aspect	Prompts	Tools	Resources
Purpose	Guide interactions	Perform actions	Expose data
Returns	Message templates	Action results	Content/data
Use case	Conversation starters, templates	Operations	Files, configs
Invocation	User selects prompt	Agent calls tool	Agent reads resource

Get Started

MCP Server

MCP Client

MCP Agents

Development

Example

Anatomy of a Prompt

Argument Descriptions

Minimal Definition

Using Context

Multi-Message Prompts

Async Prompts

Prompts vs Tools vs Resources

​Example

​Anatomy of a Prompt

​Argument Descriptions

​Minimal Definition

​Using Context

​Multi-Message Prompts

​Async Prompts

​Prompts vs Tools vs Resources

Example

Anatomy of a Prompt

Argument Descriptions

Minimal Definition

Using Context

Multi-Message Prompts

Async Prompts

Prompts vs Tools vs Resources