User Interaction Model
Prompts are designed to be user-controlled, meaning they are exposed from servers to clients with the intention of the user being able to explicitly select them for use. Typically, prompts would be triggered through user-initiated commands in the user interface, which allows users to naturally discover and invoke available prompts. For example, as slash commands: However, implementors are free to expose prompts through any interface pattern that suits their needs—the protocol itself does not mandate any specific user interaction model.Capabilities
Servers that support prompts MUST declare theprompts capability during
initialization:
{
"capabilities": {
"prompts": {
"listChanged": true
}
}
}
listChanged indicates whether the server will emit notifications when the list of
available prompts changes.
Protocol Messages
Listing Prompts
To retrieve available prompts, clients send aprompts/list request. This operation
supports pagination.
Request:
{
"jsonrpc": "2.0",
"id": 1,
"method": "prompts/list",
"params": {
"cursor": "optional-cursor-value"
}
}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"prompts": [
{
"name": "code_review",
"title": "Request Code Review",
"description": "Asks the LLM to analyze code quality and suggest improvements",
"arguments": [
{
"name": "code",
"description": "The code to review",
"required": true
}
],
"icons": [
{
"src": "https://example.com/review-icon.svg",
"mimeType": "image/svg+xml",
"sizes": ["any"]
}
]
}
],
"nextCursor": "next-page-cursor"
}
}
Getting a Prompt
To retrieve a specific prompt, clients send aprompts/get request. Arguments may be
auto-completed through the completion API.
Request:
{
"jsonrpc": "2.0",
"id": 2,
"method": "prompts/get",
"params": {
"name": "code_review",
"arguments": {
"code": "def hello():\n print('world')"
}
}
}
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"description": "Code review prompt",
"messages": [
{
"role": "user",
"content": {
"type": "text",
"text": "Please review this Python code:\ndef hello():\n print('world')"
}
}
]
}
}
List Changed Notification
When the list of available prompts changes, servers that declared thelistChanged
capability SHOULD send a notification:
{
"jsonrpc": "2.0",
"method": "notifications/prompts/list_changed"
}
Message Flow
Data Types
Prompt
A prompt definition includes:name: Unique identifier for the prompttitle: Optional human-readable name of the prompt for display purposes.description: Optional human-readable descriptionicons: Optional array of icons for display in user interfacesarguments: Optional list of arguments for customization
PromptMessage
Messages in a prompt can contain:role: Either “user” or “assistant” to indicate the speakercontent: One of the following content types:
All content types in prompt messages support optional
annotations for metadata about audience, priority,
and modification times.
Text Content
Text content represents plain text messages:{
"type": "text",
"text": "The text content of the message"
}
Image Content
Image content allows including visual information in messages:{
"type": "image",
"data": "base64-encoded-image-data",
"mimeType": "image/png"
}
Audio Content
Audio content allows including audio information in messages:{
"type": "audio",
"data": "base64-encoded-audio-data",
"mimeType": "audio/wav"
}
Embedded Resources
Embedded resources allow referencing server-side resources directly in messages:{
"type": "resource",
"resource": {
"uri": "resource://example",
"mimeType": "text/plain",
"text": "Resource content"
}
}
- A valid resource URI
- The appropriate MIME type
- Either text content or base64-encoded blob data
Error Handling
Servers SHOULD return standard JSON-RPC errors for common failure cases:- Invalid prompt name:
-32602(Invalid params) - Missing required arguments:
-32602(Invalid params) - Internal errors:
-32603(Internal error)
Implementation Considerations
- Servers SHOULD validate prompt arguments before processing
- Clients SHOULD handle pagination for large prompt lists
- Both parties SHOULD respect capability negotiation