Prompts
Create reusable, parameterized prompt templates for MCP clients.
Prompts are reusable message templates that help LLMs generate structured, purposeful responses. FastMCP simplifies defining these templates, primarily using the @mcp.prompt
decorator.
What Are Prompts?
Prompts provide parameterized message templates for LLMs. When a client requests a prompt:
- FastMCP finds the corresponding prompt definition.
- If it has parameters, they are validated against your function signature.
- Your function executes with the validated inputs.
- The generated message(s) are returned to the LLM to guide its response.
This allows you to define consistent, reusable templates that LLMs can use across different clients and contexts.
Prompts
The @prompt
Decorator
The most common way to define a prompt is by decorating a Python function. The decorator uses the function name as the prompt’s identifier.
Key Concepts:
- Name: By default, the prompt name is taken from the function name.
- Parameters: The function parameters define the inputs needed to generate the prompt.
- Inferred Metadata: By default:
- Prompt Name: Taken from the function name (
ask_about_topic
). - Prompt Description: Taken from the function’s docstring.
- Prompt Name: Taken from the function name (
Functions with *args
or **kwargs
are not supported as prompts. This restriction exists because FastMCP needs to generate a complete parameter schema for the MCP protocol, which isn’t possible with variable argument lists.
Decorator Arguments
While FastMCP infers the name and description from your function, you can override these and add additional metadata using arguments to the @mcp.prompt
decorator:
@prompt Decorator Arguments
Sets the explicit prompt name exposed via MCP. If not provided, uses the function name
Provides the description exposed via MCP. If set, the function’s docstring is ignored for this purpose
A set of strings used to categorize the prompt. Clients might use tags to filter or group available prompts
A boolean to enable or disable the prompt. See Disabling Prompts for more information
Argument Types
New in version: 2.9.0
The MCP specification requires that all prompt arguments be passed as strings, but FastMCP allows you to use typed annotations for better developer experience. When you use complex types like list[int]
or dict[str, str]
, FastMCP:
- Automatically converts string arguments from MCP clients to the expected types
- Generates helpful descriptions showing the exact JSON string format needed
- Preserves direct usage - you can still call prompts with properly typed arguments
Since the MCP specification only allows string arguments, clients need to know what string format to use for complex types. FastMCP solves this by automatically enhancing the argument descriptions with JSON schema information, making it clear to both humans and LLMs how to format their arguments.
MCP clients will call this prompt with string arguments:
But you can still call it directly with proper types:
Keep your type annotations simple when using this feature. Complex nested types or custom classes may not convert reliably from JSON strings. The automatically generated schema descriptions are the only guidance users receive about the expected format.
Good choices: list[int]
, dict[str, str]
, float
, bool
Avoid: Complex Pydantic models, deeply nested structures, custom classes
Return Values
FastMCP intelligently handles different return types from your prompt function:
str
: Automatically converted to a singlePromptMessage
.PromptMessage
: Used directly as provided. (Note a more user-friendlyMessage
constructor is available that can accept raw strings instead ofTextContent
objects.)list[PromptMessage | str]
: Used as a sequence of messages (a conversation).Any
: If the return type is not one of the above, the return value is attempted to be converted to a string and used as aPromptMessage
.
Required vs. Optional Parameters
Parameters in your function signature are considered required unless they have a default value.
In this example, the client must provide data_uri
. If analysis_type
or include_charts
are omitted, their default values will be used.
Disabling Prompts
New in version: 2.8.0
You can control the visibility and availability of prompts by enabling or disabling them. Disabled prompts will not appear in the list of available prompts, and attempting to call a disabled prompt will result in an “Unknown prompt” error.
By default, all prompts are enabled. You can disable a prompt upon creation using the enabled
parameter in the decorator:
You can also toggle a prompt’s state programmatically after it has been created:
Async Prompts
FastMCP seamlessly supports both standard (def
) and asynchronous (async def
) functions as prompts.
Use async def
when your prompt function performs I/O operations like network requests, database queries, file I/O, or external service calls.
Accessing MCP Context
New in version: 2.2.5
Prompts can access additional MCP information and features through the Context
object. To access it, add a parameter to your prompt function with a type annotation of Context
:
For full documentation on the Context object and all its capabilities, see the Context documentation.
Notifications
New in version: 2.9.1
FastMCP automatically sends notifications/prompts/list_changed
notifications to connected clients when prompts are added, enabled, or disabled. This allows clients to stay up-to-date with the current prompt set without manually polling for changes.
Notifications are only sent when these operations occur within an active MCP request context (e.g., when called from within a tool or other MCP operation). Operations performed during server initialization do not trigger notifications.
Clients can handle these notifications using a message handler to automatically refresh their prompt lists or update their interfaces.
Server Behavior
Duplicate Prompts
New in version: 2.1.0
You can configure how the FastMCP server handles attempts to register multiple prompts with the same name. Use the on_duplicate_prompts
setting during FastMCP
initialization.
The duplicate behavior options are:
"warn"
(default): Logs a warning, and the new prompt replaces the old one."error"
: Raises aValueError
, preventing the duplicate registration."replace"
: Silently replaces the existing prompt with the new one."ignore"
: Keeps the original prompt and ignores the new registration attempt.