The Model Context Protocol (MCP) introduces a standardized way for servers to expose structured prompt templates to clients. Instead of hardcoding prompts within applications, MCP enables a more dynamic and discoverable approach where prompts are treated as first class, server defined capabilities.
This shifts prompt management from being scattered across client logic to being centrally defined, versioned, and controlled by servers.
Why This Matters
In traditional LLM integrations, prompts are:
· Embedded directly in UI or backend code
· Hard to reuse across applications
· Difficult to update without redeployments
MCP solves these problems by:
· Allowing servers to define reusable prompt templates
· Enabling clients to dynamically discover available prompts
· Supporting parameterized prompts through arguments
· Providing a consistent protocol for prompt retrieval and execution
This makes prompt usage more modular, maintainable, and scalable.
1. Understanding MCP Server Capabilities
The initialize request plays a crucial role in the MCP lifecycle, it acts as a handshake between client and server, allowing the client to understand what features the server supports before making further requests.
For example, take a look at following request.
curl --location 'http://localhost:8080/mcp' \
--header 'Content-Type: application/json' \
--data '{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"clientInfo": {
"name": "my-client",
"version": "1.0.0"
},
"capabilities": {}
}
}'
In the example above, the server responds with a capabilities object that clearly defines the features it exposes. The response looks like below.
{
"result": {
"capabilities": {
"resources": {
"listChanged": true,
"subscribe": false
},
"tools": {
"listChanged": true
},
"prompts": {
"listChanged": true
}
},
"serverInfo": {
"name": "employee-mcp-server",
"version": "0.0.1"
},
"protocolVersion": "2024-11-05"
},
"id": 1,
"jsonrpc": "2.0"
}
Each capability may also include additional metadata like listChanged, which signals whether the server can notify clients about updates dynamically.
2. Listing Available Prompts
To discover the prompts exposed by an MCP server, clients send a prompts/list request. This API allows clients to retrieve all available prompt templates and supports pagination using an optional cursor.
Request Payload
{
"jsonrpc": "2.0",
"id": 1,
"method": "prompts/list",
"params": {
"cursor": "optional-cursor-value"
}
}
'cursor' is optional, and is used for pagination when the prompt list is large. Clients can pass the cursor from a previous response to fetch the next set of prompts.
Sample CURL request for the same
curl --location 'http://localhost:8080/mcp' \
--header 'Content-Type: application/json' \
--data '{
"jsonrpc": "2.0",
"id": 1,
"method": "prompts/list",
"params": {
"cursor": "optional-cursor-value"
}
}'
Sample Response looks like below
{
"result": {
"prompts": [
{
"name": "employee-profile-summary",
"description": "Generate a comprehensive summary of an employee's profile including name, department, role, and key achievements",
"arguments": [
{
"name": "employeeId",
"description": "The unique identifier of the employee",
"required": true
}
]
},
{
"name": "team-performance-analysis",
"description": "Analyze team performance metrics and generate insights about productivity, collaboration, and areas for improvement",
"arguments": [
{
"name": "departmentId",
"description": "The unique identifier of the department",
"required": true
},
{
"name": "period",
"description": "The analysis period (e.g., 'Q1', 'monthly')",
"required": false
}
]
},
{
"name": "salary-review-recommendation",
"description": "Generate salary review recommendations based on employee performance, market data, and company guidelines",
"arguments": [
{
"name": "employeeId",
"description": "The unique identifier of the employee",
"required": true
},
{
"name": "fiscalYear",
"description": "The fiscal year for the review",
"required": true
}
]
},
{
"name": "onboarding-checklist",
"description": "Generate a customized onboarding checklist for a new employee based on their role and department",
"arguments": [
{
"name": "role",
"description": "The position/role of the new employee",
"required": true
},
{
"name": "department",
"description": "The department the employee will join",
"required": true
}
]
}
]
},
"id": 1,
"jsonrpc": "2.0"
}
Each prompt returned by the server represents a reusable, parameterized template:
· name: Unique identifier used to retrieve or execute the prompt
· description: Explains the purpose of the prompt
· arguments: Defines the inputs required to customize the prompt
o name: Argument identifier
o description: What the argument represents
o required: Whether the argument must be provided
This response enables clients to dynamically:
· Discover available prompt capabilities without prior knowledge
· Render prompts as UI elements (e.g., forms, dropdowns, slash commands)
· Validate required inputs before execution
· Build flexible, user-driven workflows on top of server-defined prompts
3. Retrieving a Specific Prompt
Once a client knows which prompts are available (from prompts/list), it can fetch the full content of a specific prompt using the prompts/get request. This allows the client to see the structured messages that define the prompt, ready for execution or display.
Arguments provided in the request can be used to customize the prompt dynamically. In some implementations, arguments may also be auto-completed using the server’s completion API.
Request Payload
{
"jsonrpc": "2.0",
"id": 2,
"method": "prompts/get",
"params": {
"name": "onboarding-checklist",
"arguments": {
"code": "def hello():\n print('world')"
}
}
}
Curl Example
curl --location 'http://localhost:8080/mcp' \
--header 'Content-Type: application/json' \
--data '{
"jsonrpc": "2.0",
"id": 2,
"method": "prompts/get",
"params": {
"name": "onboarding-checklist",
"arguments": {
"code": "def hello():\n print('\''world'\'')"
}
}
}'
Sample Response
{
"result": {
"description": "Generate a customized onboarding checklist for a new employee based on their role and department",
"messages": [
{
"role": "user",
"content": {
"type": "text",
"text": "Generate a detailed onboarding checklist for a new null in the null department:\n- Pre-arrival preparation tasks\n- Day 1 orientation activities\n- Week 1 key learnings and meetings\n- First 30 days objectives\n- Training requirements by role\n- Tools and systems access procedures\n- Mentorship and pairing opportunities\n"
}
}
]
},
"id": 2,
"jsonrpc": "2.0"
}
The response provides:
· description: A human-readable explanation of what the prompt does
· messages: An array of structured messages representing the prompt content
o role: Indicates the speaker (usually "user" for client-driven prompts)
o content: The actual content of the prompt
§ type: Type of content (text, image, audio, etc.)
§ text: The message text, with placeholders (e.g., null) to be replaced with actual argument values
This structure makes it easy for clients to render prompts in the UI, fill in arguments dynamically, and send them to the LLM for execution.
4. List Changed Notification
MCP servers can notify clients when the list of available prompts changes. This is particularly useful for clients that want to keep their prompt UI up-to-date dynamically without having to continuously poll the server.
To support this, servers that declare the listChanged capability in their prompts section SHOULD send a notification whenever a prompt is added, updated, or removed.
Notification Example
{
"jsonrpc": "2.0",
"method": "notifications/prompts/list_changed"
}
In short, listChanged notifications enable proactive synchronization between MCP servers and clients, ensuring that users always have access to the most current prompt templates.
Previous Next Home
No comments:
Post a Comment