Model Context Protocol in OCaml
anil.recoil.org
1---
2title: Prompts
3weight: 10
4---
5
6{{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}}
7
8The Model Context Protocol (MCP) provides a standardized way for servers to expose prompt
9templates to clients. Prompts allow servers to provide structured messages and
10instructions for interacting with language models. Clients can discover available
11prompts, retrieve their contents, and provide arguments to customize them.
12
13## User Interaction Model
14
15Prompts are designed to be **user-controlled**, meaning they are exposed from servers to
16clients with the intention of the user being able to explicitly select them for use.
17
18Typically, prompts would be triggered through user-initiated commands in the user
19interface, which allows users to naturally discover and invoke available prompts.
20
21For example, as slash commands:
22
23
24
25However, implementors are free to expose prompts through any interface pattern that suits
26their needs—the protocol itself does not mandate any specific user interaction
27model.
28
29## Capabilities
30
31Servers that support prompts **MUST** declare the `prompts` capability during
32[initialization]({{< ref "../basic/lifecycle#initialization" >}}):
33
34/draft`json { "capabilities": { "prompts": { "listChanged": true } } }
35
36````
37
38`listChanged` indicates whether the server will emit notifications when the list of
39available prompts changes.
40
41## Protocol Messages
42
43### Listing Prompts
44
45To retrieve available prompts, clients send a `prompts/list` request. This operation
46supports [pagination]({{< ref "utilities/pagination" >}}).
47
48**Request:**
49
50```json
51{
52 "jsonrpc": "2.0",
53 "id": 1,
54 "method": "prompts/list",
55 "params": {
56 "cursor": "optional-cursor-value"
57 }
58}
59````
60
61**Response:**
62
63```json
64{
65 "jsonrpc": "2.0",
66 "id": 1,
67 "result": {
68 "prompts": [
69 {
70 "name": "code_review",
71 "description": "Asks the LLM to analyze code quality and suggest improvements",
72 "arguments": [
73 {
74 "name": "code",
75 "description": "The code to review",
76 "required": true
77 }
78 ]
79 }
80 ],
81 "nextCursor": "next-page-cursor"
82 }
83}
84```
85
86### Getting a Prompt
87
88To retrieve a specific prompt, clients send a `prompts/get` request. Arguments may be
89auto-completed through [the completion API]({{< ref "utilities/completion" >}}).
90
91**Request:**
92
93```json
94{
95 "jsonrpc": "2.0",
96 "id": 2,
97 "method": "prompts/get",
98 "params": {
99 "name": "code_review",
100 "arguments": {
101 "code": "def hello():\n print('world')"
102 }
103 }
104}
105```
106
107**Response:**
108
109```json
110{
111 "jsonrpc": "2.0",
112 "id": 2,
113 "result": {
114 "description": "Code review prompt",
115 "messages": [
116 {
117 "role": "user",
118 "content": {
119 "type": "text",
120 "text": "Please review this Python code:\ndef hello():\n print('world')"
121 }
122 }
123 ]
124 }
125}
126```
127
128### List Changed Notification
129
130When the list of available prompts changes, servers that declared the `listChanged`
131capability **SHOULD** send a notification:
132
133```json
134{
135 "jsonrpc": "2.0",
136 "method": "notifications/prompts/list_changed"
137}
138```
139
140## Message Flow
141
142```mermaid
143sequenceDiagram
144 participant Client
145 participant Server
146
147 Note over Client,Server: Discovery
148 Client->>Server: prompts/list
149 Server-->>Client: List of prompts
150
151 Note over Client,Server: Usage
152 Client->>Server: prompts/get
153 Server-->>Client: Prompt content
154
155 opt listChanged
156 Note over Client,Server: Changes
157 Server--)Client: prompts/list_changed
158 Client->>Server: prompts/list
159 Server-->>Client: Updated prompts
160 end
161```
162
163## Data Types
164
165### Prompt
166
167A prompt definition includes:
168
169- `name`: Unique identifier for the prompt
170- `description`: Optional human-readable description
171- `arguments`: Optional list of arguments for customization
172
173### PromptMessage
174
175Messages in a prompt can contain:
176
177- `role`: Either "user" or "assistant" to indicate the speaker
178- `content`: One of the following content types:
179
180#### Text Content
181
182Text content represents plain text messages:
183
184```json
185{
186 "type": "text",
187 "text": "The text content of the message"
188}
189```
190
191This is the most common content type used for natural language interactions.
192
193#### Image Content
194
195Image content allows including visual information in messages:
196
197```json
198{
199 "type": "image",
200 "data": "base64-encoded-image-data",
201 "mimeType": "image/png"
202}
203```
204
205The image data **MUST** be base64-encoded and include a valid MIME type. This enables
206multi-modal interactions where visual context is important.
207
208#### Audio Content
209
210Audio content allows including audio information in messages:
211
212```json
213{
214 "type": "audio",
215 "data": "base64-encoded-audio-data",
216 "mimeType": "audio/wav"
217}
218```
219
220The audio data MUST be base64-encoded and include a valid MIME type. This enables
221multi-modal interactions where audio context is important.
222
223#### Embedded Resources
224
225Embedded resources allow referencing server-side resources directly in messages:
226
227```json
228{
229 "type": "resource",
230 "resource": {
231 "uri": "resource://example",
232 "mimeType": "text/plain",
233 "text": "Resource content"
234 }
235}
236```
237
238Resources can contain either text or binary (blob) data and **MUST** include:
239
240- A valid resource URI
241- The appropriate MIME type
242- Either text content or base64-encoded blob data
243
244Embedded resources enable prompts to seamlessly incorporate server-managed content like
245documentation, code samples, or other reference materials directly into the conversation
246flow.
247
248## Error Handling
249
250Servers **SHOULD** return standard JSON-RPC errors for common failure cases:
251
252- Invalid prompt name: `-32602` (Invalid params)
253- Missing required arguments: `-32602` (Invalid params)
254- Internal errors: `-32603` (Internal error)
255
256## Implementation Considerations
257
2581. Servers **SHOULD** validate prompt arguments before processing
2592. Clients **SHOULD** handle pagination for large prompt lists
2603. Both parties **SHOULD** respect capability negotiation
261
262## Security
263
264Implementations **MUST** carefully validate all prompt inputs and outputs to prevent
265injection attacks or unauthorized access to resources.