This is page 2 of 3. Use http://codebase.md/r3-yamauchi/kintone-mcp-server?lines=true&page={x} to view the full context.
# Directory Structure
```
├── .gitignore
├── .mcpbignore
├── .npmrc
├── AGENTS.md
├── CLAUDE.md
├── docs
│ ├── images
│ │ ├── mcpb-install0.png
│ │ ├── mcpb-install1.png
│ │ ├── mcpb-install2.png
│ │ ├── mcpb-install3.png
│ │ ├── mcpb-install4.png
│ │ ├── mcpb-install5.png
│ │ ├── mcpb-install6.png
│ │ ├── mcpb-install7.png
│ │ ├── tool.png
│ │ └── tools.png
│ ├── mcp-server-architecture.md
│ ├── mcp-specification
│ │ ├── 2024-11-05.txt
│ │ └── 2025-03-26.txt
│ └── tool-annotations.md
├── LICENSE
├── manifest.json
├── package-lock.json
├── package.json
├── pnpm-lock.yaml
├── README.md
├── renovate.json
├── scripts
│ └── ensure-pnpm.js
├── server.js
├── src
│ ├── constants.js
│ ├── index.js
│ ├── models
│ │ ├── KintoneCredentials.js
│ │ └── KintoneRecord.js
│ ├── repositories
│ │ ├── base
│ │ │ ├── BaseKintoneRepository.js
│ │ │ └── http
│ │ │ ├── createKintoneClient.js
│ │ │ ├── KintoneApiError.js
│ │ │ └── KintoneHttpClient.js
│ │ ├── KintoneAppRepository.js
│ │ ├── KintoneFileRepository.js
│ │ ├── KintoneFormRepository.js
│ │ ├── KintonePreviewRepository.js
│ │ ├── KintoneRecordRepository.js
│ │ ├── KintoneRepository.js
│ │ ├── KintoneSpaceRepository.js
│ │ ├── KintoneUserRepository.js
│ │ └── validators
│ │ ├── FieldValidator.js
│ │ ├── LayoutValidator.js
│ │ └── OptionValidator.js
│ ├── server
│ │ ├── handlers
│ │ │ ├── ErrorHandlers.js
│ │ │ ├── ToolRequestHandler.js
│ │ │ └── ToolRouter.js
│ │ ├── MCPServer.js
│ │ └── tools
│ │ ├── AppTools.js
│ │ ├── BaseToolHandler.js
│ │ ├── definitions
│ │ │ ├── AppToolDefinitions.js
│ │ │ ├── DocumentationToolDefinitions.js
│ │ │ ├── FieldToolDefinitions.js
│ │ │ ├── FileToolDefinitions.js
│ │ │ ├── index.js
│ │ │ ├── LayoutToolDefinitions.js
│ │ │ ├── RecordToolDefinitions.js
│ │ │ ├── SpaceToolDefinitions.js
│ │ │ ├── SystemToolDefinitions.js
│ │ │ └── UserToolDefinitions.js
│ │ ├── documentation
│ │ │ ├── calcField.js
│ │ │ ├── choiceFields.js
│ │ │ ├── dateField.js
│ │ │ ├── dateTimeField.js
│ │ │ ├── fileField.js
│ │ │ ├── index.js
│ │ │ ├── layoutFields.js
│ │ │ ├── linkField.js
│ │ │ ├── lookup.js
│ │ │ ├── numberField.js
│ │ │ ├── otherFields.js
│ │ │ ├── queryLanguage.js
│ │ │ ├── referenceTable.js
│ │ │ ├── richText.js
│ │ │ ├── subtable.js
│ │ │ ├── systemFields.js
│ │ │ ├── textFields.js
│ │ │ ├── timeField.js
│ │ │ └── userSelect.js
│ │ ├── DocumentationTools.js
│ │ ├── FieldTools.js
│ │ ├── FileTools.js
│ │ ├── LayoutTools.js
│ │ ├── RecordTools.js
│ │ ├── SpaceTools.js
│ │ ├── SystemTools.js
│ │ └── UserTools.js
│ └── utils
│ ├── DataTransformers.js
│ ├── FieldValidationUtils.js
│ ├── index.js
│ ├── LayoutUtils.js
│ ├── LoggingUtils.js
│ ├── ResponseBuilder.js
│ └── ValidationUtils.js
└── unofficial-kintone-mcp-server-8.0.0.mcpb
```
# Files
--------------------------------------------------------------------------------
/docs/mcp-specification/2024-11-05.txt:
--------------------------------------------------------------------------------
```
1 | └── docs
2 | └── specification
3 | └── 2024-11-05
4 | ├── _index.md
5 | ├── architecture
6 | └── _index.md
7 | ├── basic
8 | ├── _index.md
9 | ├── lifecycle.md
10 | ├── messages.md
11 | ├── transports.md
12 | └── utilities
13 | │ ├── _index.md
14 | │ ├── cancellation.md
15 | │ ├── ping.md
16 | │ └── progress.md
17 | ├── client
18 | ├── _index.md
19 | ├── roots.md
20 | └── sampling.md
21 | └── server
22 | ├── _index.md
23 | ├── prompts.md
24 | ├── resource-picker.png
25 | ├── resources.md
26 | ├── slash-command.png
27 | ├── tools.md
28 | └── utilities
29 | ├── _index.md
30 | ├── completion.md
31 | ├── logging.md
32 | └── pagination.md
33 |
34 |
35 | /docs/specification/2024-11-05/_index.md:
36 | --------------------------------------------------------------------------------
37 | 1 | ---
38 | 2 | linkTitle: 2024-11-05 (Final)
39 | 3 | title: Model Context Protocol specification
40 | 4 | cascade:
41 | 5 | type: docs
42 | 6 | breadcrumbs: false
43 | 7 | weight: 2
44 | 8 | ---
45 | 9 |
46 | 10 | {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
47 | 11 |
48 | 12 | [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open protocol that
49 | 13 | enables seamless integration between LLM applications and external data sources and
50 | 14 | tools. Whether you're building an AI-powered IDE, enhancing a chat interface, or creating
51 | 15 | custom AI workflows, MCP provides a standardized way to connect LLMs with the context
52 | 16 | they need.
53 | 17 |
54 | 18 | This specification defines the authoritative protocol requirements, based on the
55 | 19 | TypeScript schema in
56 | 20 | [schema.ts](https://github.com/modelcontextprotocol/specification/blob/main/schema/2024-11-05/schema.ts).
57 | 21 |
58 | 22 | For implementation guides and examples, visit
59 | 23 | [modelcontextprotocol.io](https://modelcontextprotocol.io).
60 | 24 |
61 | 25 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD
62 | 26 | NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
63 | 27 | interpreted as described in [BCP 14](https://datatracker.ietf.org/doc/html/bcp14)
64 | 28 | [[RFC2119](https://datatracker.ietf.org/doc/html/rfc2119)]
65 | 29 | [[RFC8174](https://datatracker.ietf.org/doc/html/rfc8174)] when, and only when, they
66 | 30 | appear in all capitals, as shown here.
67 | 31 |
68 | 32 | ## Overview
69 | 33 |
70 | 34 | MCP provides a standardized way for applications to:
71 | 35 |
72 | 36 | - Share contextual information with language models
73 | 37 | - Expose tools and capabilities to AI systems
74 | 38 | - Build composable integrations and workflows
75 | 39 |
76 | 40 | The protocol uses [JSON-RPC](https://www.jsonrpc.org/) 2.0 messages to establish
77 | 41 | communication between:
78 | 42 |
79 | 43 | - **Hosts**: LLM applications that initiate connections
80 | 44 | - **Clients**: Connectors within the host application
81 | 45 | - **Servers**: Services that provide context and capabilities
82 | 46 |
83 | 47 | MCP takes some inspiration from the
84 | 48 | [Language Server Protocol](https://microsoft.github.io/language-server-protocol/), which
85 | 49 | standardizes how to add support for programming languages across a whole ecosystem of
86 | 50 | development tools. In a similar way, MCP standardizes how to integrate additional context
87 | 51 | and tools into the ecosystem of AI applications.
88 | 52 |
89 | 53 | ## Key Details
90 | 54 |
91 | 55 | ### Base Protocol
92 | 56 |
93 | 57 | - [JSON-RPC](https://www.jsonrpc.org/) message format
94 | 58 | - Stateful connections
95 | 59 | - Server and client capability negotiation
96 | 60 |
97 | 61 | ### Features
98 | 62 |
99 | 63 | Servers offer any of the following features to clients:
100 | 64 |
101 | 65 | - **Resources**: Context and data, for the user or the AI model to use
102 | 66 | - **Prompts**: Templated messages and workflows for users
103 | 67 | - **Tools**: Functions for the AI model to execute
104 | 68 |
105 | 69 | Clients may offer the following feature to servers:
106 | 70 |
107 | 71 | - **Sampling**: Server-initiated agentic behaviors and recursive LLM interactions
108 | 72 |
109 | 73 | ### Additional Utilities
110 | 74 |
111 | 75 | - Configuration
112 | 76 | - Progress tracking
113 | 77 | - Cancellation
114 | 78 | - Error reporting
115 | 79 | - Logging
116 | 80 |
117 | 81 | ## Security and Trust & Safety
118 | 82 |
119 | 83 | The Model Context Protocol enables powerful capabilities through arbitrary data access
120 | 84 | and code execution paths. With this power comes important security and trust
121 | 85 | considerations that all implementors must carefully address.
122 | 86 |
123 | 87 | ### Key Principles
124 | 88 |
125 | 89 | 1. **User Consent and Control**
126 | 90 |
127 | 91 | - Users must explicitly consent to and understand all data access and operations
128 | 92 | - Users must retain control over what data is shared and what actions are taken
129 | 93 | - Implementors should provide clear UIs for reviewing and authorizing activities
130 | 94 |
131 | 95 | 2. **Data Privacy**
132 | 96 |
133 | 97 | - Hosts must obtain explicit user consent before exposing user data to servers
134 | 98 | - Hosts must not transmit resource data elsewhere without user consent
135 | 99 | - User data should be protected with appropriate access controls
136 | 100 |
137 | 101 | 3. **Tool Safety**
138 | 102 |
139 | 103 | - Tools represent arbitrary code execution and must be treated with appropriate
140 | 104 | caution
141 | 105 | - Hosts must obtain explicit user consent before invoking any tool
142 | 106 | - Users should understand what each tool does before authorizing its use
143 | 107 |
144 | 108 | 4. **LLM Sampling Controls**
145 | 109 | - Users must explicitly approve any LLM sampling requests
146 | 110 | - Users should control:
147 | 111 | - Whether sampling occurs at all
148 | 112 | - The actual prompt that will be sent
149 | 113 | - What results the server can see
150 | 114 | - The protocol intentionally limits server visibility into prompts
151 | 115 |
152 | 116 | ### Implementation Guidelines
153 | 117 |
154 | 118 | While MCP itself cannot enforce these security principles at the protocol level,
155 | 119 | implementors **SHOULD**:
156 | 120 |
157 | 121 | 1. Build robust consent and authorization flows into their applications
158 | 122 | 2. Provide clear documentation of security implications
159 | 123 | 3. Implement appropriate access controls and data protections
160 | 124 | 4. Follow security best practices in their integrations
161 | 125 | 5. Consider privacy implications in their feature designs
162 | 126 |
163 | 127 | ## Learn More
164 | 128 |
165 | 129 | Explore the detailed specification for each protocol component:
166 | 130 |
167 | 131 | {{< cards >}} {{< card link="architecture" title="Architecture" icon="template" >}}
168 | 132 | {{< card link="basic" title="Base Protocol" icon="code" >}}
169 | 133 | {{< card link="server" title="Server Features" icon="server" >}}
170 | 134 | {{< card link="client" title="Client Features" icon="user" >}}
171 | 135 | {{< card link="contributing" title="Contributing" icon="pencil" >}} {{< /cards >}}
172 | 136 |
173 |
174 |
175 | --------------------------------------------------------------------------------
176 | /docs/specification/2024-11-05/architecture/_index.md:
177 | --------------------------------------------------------------------------------
178 | 1 | ---
179 | 2 | title: Architecture
180 | 3 | cascade:
181 | 4 | type: docs
182 | 5 | weight: 1
183 | 6 | ---
184 | 7 |
185 | 8 | The Model Context Protocol (MCP) follows a client-host-server architecture where each
186 | 9 | host can run multiple client instances. This architecture enables users to integrate AI
187 | 10 | capabilities across applications while maintaining clear security boundaries and
188 | 11 | isolating concerns. Built on JSON-RPC, MCP provides a stateful session protocol focused
189 | 12 | on context exchange and sampling coordination between clients and servers.
190 | 13 |
191 | 14 | ## Core Components
192 | 15 |
193 | 16 | ```mermaid
194 | 17 | graph LR
195 | 18 | subgraph "Application Host Process"
196 | 19 | H[Host]
197 | 20 | C1[Client 1]
198 | 21 | C2[Client 2]
199 | 22 | C3[Client 3]
200 | 23 | H --> C1
201 | 24 | H --> C2
202 | 25 | H --> C3
203 | 26 | end
204 | 27 |
205 | 28 | subgraph "Local machine"
206 | 29 | S1[Server 1<br>Files & Git]
207 | 30 | S2[Server 2<br>Database]
208 | 31 | R1[("Local<br>Resource A")]
209 | 32 | R2[("Local<br>Resource B")]
210 | 33 |
211 | 34 | C1 --> S1
212 | 35 | C2 --> S2
213 | 36 | S1 <--> R1
214 | 37 | S2 <--> R2
215 | 38 | end
216 | 39 |
217 | 40 | subgraph "Internet"
218 | 41 | S3[Server 3<br>External APIs]
219 | 42 | R3[("Remote<br>Resource C")]
220 | 43 |
221 | 44 | C3 --> S3
222 | 45 | S3 <--> R3
223 | 46 | end
224 | 47 | ```
225 | 48 |
226 | 49 | ### Host
227 | 50 |
228 | 51 | The host process acts as the container and coordinator:
229 | 52 |
230 | 53 | - Creates and manages multiple client instances
231 | 54 | - Controls client connection permissions and lifecycle
232 | 55 | - Enforces security policies and consent requirements
233 | 56 | - Handles user authorization decisions
234 | 57 | - Coordinates AI/LLM integration and sampling
235 | 58 | - Manages context aggregation across clients
236 | 59 |
237 | 60 | ### Clients
238 | 61 |
239 | 62 | Each client is created by the host and maintains an isolated server connection:
240 | 63 |
241 | 64 | - Establishes one stateful session per server
242 | 65 | - Handles protocol negotiation and capability exchange
243 | 66 | - Routes protocol messages bidirectionally
244 | 67 | - Manages subscriptions and notifications
245 | 68 | - Maintains security boundaries between servers
246 | 69 |
247 | 70 | A host application creates and manages multiple clients, with each client having a 1:1
248 | 71 | relationship with a particular server.
249 | 72 |
250 | 73 | ### Servers
251 | 74 |
252 | 75 | Servers provide specialized context and capabilities:
253 | 76 |
254 | 77 | - Expose resources, tools and prompts via MCP primitives
255 | 78 | - Operate independently with focused responsibilities
256 | 79 | - Request sampling through client interfaces
257 | 80 | - Must respect security constraints
258 | 81 | - Can be local processes or remote services
259 | 82 |
260 | 83 | ## Design Principles
261 | 84 |
262 | 85 | MCP is built on several key design principles that inform its architecture and
263 | 86 | implementation:
264 | 87 |
265 | 88 | 1. **Servers should be extremely easy to build**
266 | 89 |
267 | 90 | - Host applications handle complex orchestration responsibilities
268 | 91 | - Servers focus on specific, well-defined capabilities
269 | 92 | - Simple interfaces minimize implementation overhead
270 | 93 | - Clear separation enables maintainable code
271 | 94 |
272 | 95 | 2. **Servers should be highly composable**
273 | 96 |
274 | 97 | - Each server provides focused functionality in isolation
275 | 98 | - Multiple servers can be combined seamlessly
276 | 99 | - Shared protocol enables interoperability
277 | 100 | - Modular design supports extensibility
278 | 101 |
279 | 102 | 3. **Servers should not be able to read the whole conversation, nor "see into" other
280 | 103 | servers**
281 | 104 |
282 | 105 | - Servers receive only necessary contextual information
283 | 106 | - Full conversation history stays with the host
284 | 107 | - Each server connection maintains isolation
285 | 108 | - Cross-server interactions are controlled by the host
286 | 109 | - Host process enforces security boundaries
287 | 110 |
288 | 111 | 4. **Features can be added to servers and clients progressively**
289 | 112 | - Core protocol provides minimal required functionality
290 | 113 | - Additional capabilities can be negotiated as needed
291 | 114 | - Servers and clients evolve independently
292 | 115 | - Protocol designed for future extensibility
293 | 116 | - Backwards compatibility is maintained
294 | 117 |
295 | 118 | ## Message Types
296 | 119 |
297 | 120 | MCP defines three core message types based on
298 | 121 | [JSON-RPC 2.0](https://www.jsonrpc.org/specification):
299 | 122 |
300 | 123 | - **Requests**: Bidirectional messages with method and parameters expecting a response
301 | 124 | - **Responses**: Successful results or errors matching specific request IDs
302 | 125 | - **Notifications**: One-way messages requiring no response
303 | 126 |
304 | 127 | Each message type follows the JSON-RPC 2.0 specification for structure and delivery
305 | 128 | semantics.
306 | 129 |
307 | 130 | ## Capability Negotiation
308 | 131 |
309 | 132 | The Model Context Protocol uses a capability-based negotiation system where clients and
310 | 133 | servers explicitly declare their supported features during initialization. Capabilities
311 | 134 | determine which protocol features and primitives are available during a session.
312 | 135 |
313 | 136 | - Servers declare capabilities like resource subscriptions, tool support, and prompt
314 | 137 | templates
315 | 138 | - Clients declare capabilities like sampling support and notification handling
316 | 139 | - Both parties must respect declared capabilities throughout the session
317 | 140 | - Additional capabilities can be negotiated through extensions to the protocol
318 | 141 |
319 | 142 | ```mermaid
320 | 143 | sequenceDiagram
321 | 144 | participant Host
322 | 145 | participant Client
323 | 146 | participant Server
324 | 147 |
325 | 148 | Host->>+Client: Initialize client
326 | 149 | Client->>+Server: Initialize session with capabilities
327 | 150 | Server-->>Client: Respond with supported capabilities
328 | 151 |
329 | 152 | Note over Host,Server: Active Session with Negotiated Features
330 | 153 |
331 | 154 | loop Client Requests
332 | 155 | Host->>Client: User- or model-initiated action
333 | 156 | Client->>Server: Request (tools/resources)
334 | 157 | Server-->>Client: Response
335 | 158 | Client-->>Host: Update UI or respond to model
336 | 159 | end
337 | 160 |
338 | 161 | loop Server Requests
339 | 162 | Server->>Client: Request (sampling)
340 | 163 | Client->>Host: Forward to AI
341 | 164 | Host-->>Client: AI response
342 | 165 | Client-->>Server: Response
343 | 166 | end
344 | 167 |
345 | 168 | loop Notifications
346 | 169 | Server--)Client: Resource updates
347 | 170 | Client--)Server: Status changes
348 | 171 | end
349 | 172 |
350 | 173 | Host->>Client: Terminate
351 | 174 | Client->>-Server: End session
352 | 175 | deactivate Server
353 | 176 | ```
354 | 177 |
355 | 178 | Each capability unlocks specific protocol features for use during the session. For
356 | 179 | example:
357 | 180 |
358 | 181 | - Implemented [server features]({{< ref "/specification/2024-11-05/server" >}}) must be
359 | 182 | advertised in the server's capabilities
360 | 183 | - Emitting resource subscription notifications requires the server to declare
361 | 184 | subscription support
362 | 185 | - Tool invocation requires the server to declare tool capabilities
363 | 186 | - [Sampling]({{< ref "/specification/2024-11-05/client" >}}) requires the client to
364 | 187 | declare support in its capabilities
365 | 188 |
366 | 189 | This capability negotiation ensures clients and servers have a clear understanding of
367 | 190 | supported functionality while maintaining protocol extensibility.
368 | 191 |
369 |
370 |
371 | --------------------------------------------------------------------------------
372 | /docs/specification/2024-11-05/basic/_index.md:
373 | --------------------------------------------------------------------------------
374 | 1 | ---
375 | 2 | title: Base Protocol
376 | 3 | cascade:
377 | 4 | type: docs
378 | 5 | weight: 2
379 | 6 | ---
380 | 7 |
381 | 8 | {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
382 | 9 |
383 | 10 | All messages between MCP clients and servers **MUST** follow the
384 | 11 | [JSON-RPC 2.0](https://www.jsonrpc.org/specification) specification. The protocol defines
385 | 12 | three fundamental types of messages:
386 | 13 |
387 | 14 | | Type | Description | Requirements |
388 | 15 | | --------------- | -------------------------------------- | -------------------------------------- |
389 | 16 | | `Requests` | Messages sent to initiate an operation | Must include unique ID and method name |
390 | 17 | | `Responses` | Messages sent in reply to requests | Must include same ID as request |
391 | 18 | | `Notifications` | One-way messages with no reply | Must not include an ID |
392 | 19 |
393 | 20 | **Responses** are further sub-categorized as either **successful results** or **errors**.
394 | 21 | Results can follow any JSON object structure, while errors must include an error code and
395 | 22 | message at minimum.
396 | 23 |
397 | 24 | ## Protocol Layers
398 | 25 |
399 | 26 | The Model Context Protocol consists of several key components that work together:
400 | 27 |
401 | 28 | - **Base Protocol**: Core JSON-RPC message types
402 | 29 | - **Lifecycle Management**: Connection initialization, capability negotiation, and
403 | 30 | session control
404 | 31 | - **Server Features**: Resources, prompts, and tools exposed by servers
405 | 32 | - **Client Features**: Sampling and root directory lists provided by clients
406 | 33 | - **Utilities**: Cross-cutting concerns like logging and argument completion
407 | 34 |
408 | 35 | All implementations **MUST** support the base protocol and lifecycle management
409 | 36 | components. Other components **MAY** be implemented based on the specific needs of the
410 | 37 | application.
411 | 38 |
412 | 39 | These protocol layers establish clear separation of concerns while enabling rich
413 | 40 | interactions between clients and servers. The modular design allows implementations to
414 | 41 | support exactly the features they need.
415 | 42 |
416 | 43 | See the following pages for more details on the different components:
417 | 44 |
418 | 45 | {{< cards >}}
419 | 46 | {{< card link="/specification/2024-11-05/basic/lifecycle" title="Lifecycle" icon="refresh" >}}
420 | 47 | {{< card link="/specification/2024-11-05/server/resources" title="Resources" icon="document" >}}
421 | 48 | {{< card link="/specification/2024-11-05/server/prompts" title="Prompts" icon="chat-alt-2" >}}
422 | 49 | {{< card link="/specification/2024-11-05/server/tools" title="Tools" icon="adjustments" >}}
423 | 50 | {{< card link="/specification/2024-11-05/server/utilities/logging" title="Logging" icon="annotation" >}}
424 | 51 | {{< card link="/specification/2024-11-05/client/sampling" title="Sampling" icon="code" >}}
425 | 52 | {{< /cards >}}
426 | 53 |
427 | 54 | ## Auth
428 | 55 |
429 | 56 | Authentication and authorization are not currently part of the core MCP specification,
430 | 57 | but we are considering ways to introduce them in future. Join us in
431 | 58 | [GitHub Discussions](https://github.com/modelcontextprotocol/specification/discussions)
432 | 59 | to help shape the future of the protocol!
433 | 60 |
434 | 61 | Clients and servers **MAY** negotiate their own custom authentication and authorization
435 | 62 | strategies.
436 | 63 |
437 | 64 | ## Schema
438 | 65 |
439 | 66 | The full specification of the protocol is defined as a
440 | 67 | [TypeScript schema](http://github.com/modelcontextprotocol/specification/tree/main/schema/2024-11-05/schema.ts).
441 | 68 | This is the source of truth for all protocol messages and structures.
442 | 69 |
443 | 70 | There is also a
444 | 71 | [JSON Schema](http://github.com/modelcontextprotocol/specification/tree/main/schema/2024-11-05/schema.json),
445 | 72 | which is automatically generated from the TypeScript source of truth, for use with
446 | 73 | various automated tooling.
447 | 74 |
448 |
449 |
450 | --------------------------------------------------------------------------------
451 | /docs/specification/2024-11-05/basic/lifecycle.md:
452 | --------------------------------------------------------------------------------
453 | 1 | ---
454 | 2 | title: Lifecycle
455 | 3 | type: docs
456 | 4 | weight: 30
457 | 5 | ---
458 | 6 |
459 | 7 | {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
460 | 8 |
461 | 9 | The Model Context Protocol (MCP) defines a rigorous lifecycle for client-server
462 | 10 | connections that ensures proper capability negotiation and state management.
463 | 11 |
464 | 12 | 1. **Initialization**: Capability negotiation and protocol version agreement
465 | 13 | 2. **Operation**: Normal protocol communication
466 | 14 | 3. **Shutdown**: Graceful termination of the connection
467 | 15 |
468 | 16 | ```mermaid
469 | 17 | sequenceDiagram
470 | 18 | participant Client
471 | 19 | participant Server
472 | 20 |
473 | 21 | Note over Client,Server: Initialization Phase
474 | 22 | activate Client
475 | 23 | Client->>+Server: initialize request
476 | 24 | Server-->>Client: initialize response
477 | 25 | Client--)Server: initialized notification
478 | 26 |
479 | 27 | Note over Client,Server: Operation Phase
480 | 28 | rect rgb(200, 220, 250)
481 | 29 | note over Client,Server: Normal protocol operations
482 | 30 | end
483 | 31 |
484 | 32 | Note over Client,Server: Shutdown
485 | 33 | Client--)-Server: Disconnect
486 | 34 | deactivate Server
487 | 35 | Note over Client,Server: Connection closed
488 | 36 | ```
489 | 37 |
490 | 38 | ## Lifecycle Phases
491 | 39 |
492 | 40 | ### Initialization
493 | 41 |
494 | 42 | The initialization phase **MUST** be the first interaction between client and server.
495 | 43 | During this phase, the client and server:
496 | 44 |
497 | 45 | - Establish protocol version compatibility
498 | 46 | - Exchange and negotiate capabilities
499 | 47 | - Share implementation details
500 | 48 |
501 | 49 | The client **MUST** initiate this phase by sending an `initialize` request containing:
502 | 50 |
503 | 51 | - Protocol version supported
504 | 52 | - Client capabilities
505 | 53 | - Client implementation information
506 | 54 |
507 | 55 | ```json
508 | 56 | {
509 | 57 | "jsonrpc": "2.0",
510 | 58 | "id": 1,
511 | 59 | "method": "initialize",
512 | 60 | "params": {
513 | 61 | "protocolVersion": "2024-11-05",
514 | 62 | "capabilities": {
515 | 63 | "roots": {
516 | 64 | "listChanged": true
517 | 65 | },
518 | 66 | "sampling": {}
519 | 67 | },
520 | 68 | "clientInfo": {
521 | 69 | "name": "ExampleClient",
522 | 70 | "version": "1.0.0"
523 | 71 | }
524 | 72 | }
525 | 73 | }
526 | 74 | ```
527 | 75 |
528 | 76 | The server **MUST** respond with its own capabilities and information:
529 | 77 |
530 | 78 | ```json
531 | 79 | {
532 | 80 | "jsonrpc": "2.0",
533 | 81 | "id": 1,
534 | 82 | "result": {
535 | 83 | "protocolVersion": "2024-11-05",
536 | 84 | "capabilities": {
537 | 85 | "logging": {},
538 | 86 | "prompts": {
539 | 87 | "listChanged": true
540 | 88 | },
541 | 89 | "resources": {
542 | 90 | "subscribe": true,
543 | 91 | "listChanged": true
544 | 92 | },
545 | 93 | "tools": {
546 | 94 | "listChanged": true
547 | 95 | }
548 | 96 | },
549 | 97 | "serverInfo": {
550 | 98 | "name": "ExampleServer",
551 | 99 | "version": "1.0.0"
552 | 100 | }
553 | 101 | }
554 | 102 | }
555 | 103 | ```
556 | 104 |
557 | 105 | After successful initialization, the client **MUST** send an `initialized` notification
558 | 106 | to indicate it is ready to begin normal operations:
559 | 107 |
560 | 108 | ```json
561 | 109 | {
562 | 110 | "jsonrpc": "2.0",
563 | 111 | "method": "notifications/initialized"
564 | 112 | }
565 | 113 | ```
566 | 114 |
567 | 115 | - The client **SHOULD NOT** send requests other than
568 | 116 | [pings]({{< ref "/specification/2024-11-05/basic/utilities/ping" >}}) before the server
569 | 117 | has responded to the `initialize` request.
570 | 118 | - The server **SHOULD NOT** send requests other than
571 | 119 | [pings]({{< ref "/specification/2024-11-05/basic/utilities/ping" >}}) and
572 | 120 | [logging]({{< ref "/specification/2024-11-05/server/utilities/logging" >}}) before
573 | 121 | receiving the `initialized` notification.
574 | 122 |
575 | 123 | #### Version Negotiation
576 | 124 |
577 | 125 | In the `initialize` request, the client **MUST** send a protocol version it supports.
578 | 126 | This **SHOULD** be the _latest_ version supported by the client.
579 | 127 |
580 | 128 | If the server supports the requested protocol version, it **MUST** respond with the same
581 | 129 | version. Otherwise, the server **MUST** respond with another protocol version it
582 | 130 | supports. This **SHOULD** be the _latest_ version supported by the server.
583 | 131 |
584 | 132 | If the client does not support the version in the server's response, it **SHOULD**
585 | 133 | disconnect.
586 | 134 |
587 | 135 | #### Capability Negotiation
588 | 136 |
589 | 137 | Client and server capabilities establish which optional protocol features will be
590 | 138 | available during the session.
591 | 139 |
592 | 140 | Key capabilities include:
593 | 141 |
594 | 142 | | Category | Capability | Description |
595 | 143 | | -------- | -------------- | ------------------------------------------------------------------------------------------------- |
596 | 144 | | Client | `roots` | Ability to provide filesystem [roots]({{< ref "/specification/2024-11-05/client/roots" >}}) |
597 | 145 | | Client | `sampling` | Support for LLM [sampling]({{< ref "/specification/2024-11-05/client/sampling" >}}) requests |
598 | 146 | | Client | `experimental` | Describes support for non-standard experimental features |
599 | 147 | | Server | `prompts` | Offers [prompt templates]({{< ref "/specification/2024-11-05/server/prompts" >}}) |
600 | 148 | | Server | `resources` | Provides readable [resources]({{< ref "/specification/2024-11-05/server/resources" >}}) |
601 | 149 | | Server | `tools` | Exposes callable [tools]({{< ref "/specification/2024-11-05/server/tools" >}}) |
602 | 150 | | Server | `logging` | Emits structured [log messages]({{< ref "/specification/2024-11-05/server/utilities/logging" >}}) |
603 | 151 | | Server | `experimental` | Describes support for non-standard experimental features |
604 | 152 |
605 | 153 | Capability objects can describe sub-capabilities like:
606 | 154 |
607 | 155 | - `listChanged`: Support for list change notifications (for prompts, resources, and
608 | 156 | tools)
609 | 157 | - `subscribe`: Support for subscribing to individual items' changes (resources only)
610 | 158 |
611 | 159 | ### Operation
612 | 160 |
613 | 161 | During the operation phase, the client and server exchange messages according to the
614 | 162 | negotiated capabilities.
615 | 163 |
616 | 164 | Both parties **SHOULD**:
617 | 165 |
618 | 166 | - Respect the negotiated protocol version
619 | 167 | - Only use capabilities that were successfully negotiated
620 | 168 |
621 | 169 | ### Shutdown
622 | 170 |
623 | 171 | During the shutdown phase, one side (usually the client) cleanly terminates the protocol
624 | 172 | connection. No specific shutdown messages are defined—instead, the underlying transport
625 | 173 | mechanism should be used to signal connection termination:
626 | 174 |
627 | 175 | #### stdio
628 | 176 |
629 | 177 | For the stdio [transport]({{< ref "/specification/2024-11-05/basic/transports" >}}), the
630 | 178 | client **SHOULD** initiate shutdown by:
631 | 179 |
632 | 180 | 1. First, closing the input stream to the child process (the server)
633 | 181 | 2. Waiting for the server to exit, or sending `SIGTERM` if the server does not exit
634 | 182 | within a reasonable time
635 | 183 | 3. Sending `SIGKILL` if the server does not exit within a reasonable time after `SIGTERM`
636 | 184 |
637 | 185 | The server **MAY** initiate shutdown by closing its output stream to the client and
638 | 186 | exiting.
639 | 187 |
640 | 188 | #### HTTP
641 | 189 |
642 | 190 | For HTTP [transports]({{< ref "/specification/2024-11-05/basic/transports" >}}), shutdown
643 | 191 | is indicated by closing the associated HTTP connection(s).
644 | 192 |
645 | 193 | ## Error Handling
646 | 194 |
647 | 195 | Implementations **SHOULD** be prepared to handle these error cases:
648 | 196 |
649 | 197 | - Protocol version mismatch
650 | 198 | - Failure to negotiate required capabilities
651 | 199 | - Initialize request timeout
652 | 200 | - Shutdown timeout
653 | 201 |
654 | 202 | Implementations **SHOULD** implement appropriate timeouts for all requests, to prevent
655 | 203 | hung connections and resource exhaustion.
656 | 204 |
657 | 205 | Example initialization error:
658 | 206 |
659 | 207 | ```json
660 | 208 | {
661 | 209 | "jsonrpc": "2.0",
662 | 210 | "id": 1,
663 | 211 | "error": {
664 | 212 | "code": -32602,
665 | 213 | "message": "Unsupported protocol version",
666 | 214 | "data": {
667 | 215 | "supported": ["2024-11-05"],
668 | 216 | "requested": "1.0.0"
669 | 217 | }
670 | 218 | }
671 | 219 | }
672 | 220 | ```
673 | 221 |
674 |
675 |
676 | --------------------------------------------------------------------------------
677 | /docs/specification/2024-11-05/basic/messages.md:
678 | --------------------------------------------------------------------------------
679 | 1 | ---
680 | 2 | title: Messages
681 | 3 | type: docs
682 | 4 | weight: 20
683 | 5 | ---
684 | 6 |
685 | 7 | {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
686 | 8 |
687 | 9 | All messages in MCP **MUST** follow the
688 | 10 | [JSON-RPC 2.0](https://www.jsonrpc.org/specification) specification. The protocol defines
689 | 11 | three types of messages:
690 | 12 |
691 | 13 | ## Requests
692 | 14 |
693 | 15 | Requests are sent from the client to the server or vice versa.
694 | 16 |
695 | 17 | ```typescript
696 | 18 | {
697 | 19 | jsonrpc: "2.0";
698 | 20 | id: string | number;
699 | 21 | method: string;
700 | 22 | params?: {
701 | 23 | [key: string]: unknown;
702 | 24 | };
703 | 25 | }
704 | 26 | ```
705 | 27 |
706 | 28 | - Requests **MUST** include a string or integer ID.
707 | 29 | - Unlike base JSON-RPC, the ID **MUST NOT** be `null`.
708 | 30 | - The request ID **MUST NOT** have been previously used by the requestor within the same
709 | 31 | session.
710 | 32 |
711 | 33 | ## Responses
712 | 34 |
713 | 35 | Responses are sent in reply to requests.
714 | 36 |
715 | 37 | ```typescript
716 | 38 | {
717 | 39 | jsonrpc: "2.0";
718 | 40 | id: string | number;
719 | 41 | result?: {
720 | 42 | [key: string]: unknown;
721 | 43 | }
722 | 44 | error?: {
723 | 45 | code: number;
724 | 46 | message: string;
725 | 47 | data?: unknown;
726 | 48 | }
727 | 49 | }
728 | 50 | ```
729 | 51 |
730 | 52 | - Responses **MUST** include the same ID as the request they correspond to.
731 | 53 | - Either a `result` or an `error` **MUST** be set. A response **MUST NOT** set both.
732 | 54 | - Error codes **MUST** be integers.
733 | 55 |
734 | 56 | ## Notifications
735 | 57 |
736 | 58 | Notifications are sent from the client to the server or vice versa. They do not expect a
737 | 59 | response.
738 | 60 |
739 | 61 | ```typescript
740 | 62 | {
741 | 63 | jsonrpc: "2.0";
742 | 64 | method: string;
743 | 65 | params?: {
744 | 66 | [key: string]: unknown;
745 | 67 | };
746 | 68 | }
747 | 69 | ```
748 | 70 |
749 | 71 | - Notifications **MUST NOT** include an ID.
750 | 72 |
751 |
752 |
753 | --------------------------------------------------------------------------------
754 | /docs/specification/2024-11-05/basic/transports.md:
755 | --------------------------------------------------------------------------------
756 | 1 | ---
757 | 2 | title: Transports
758 | 3 | type: docs
759 | 4 | weight: 40
760 | 5 | ---
761 | 6 |
762 | 7 | {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
763 | 8 |
764 | 9 | MCP currently defines two standard transport mechanisms for client-server communication:
765 | 10 |
766 | 11 | 1. [stdio](#stdio), communication over standard in and standard out
767 | 12 | 2. [HTTP with Server-Sent Events](#http-with-sse) (SSE)
768 | 13 |
769 | 14 | Clients **SHOULD** support stdio whenever possible.
770 | 15 |
771 | 16 | It is also possible for clients and servers to implement
772 | 17 | [custom transports](#custom-transports) in a pluggable fashion.
773 | 18 |
774 | 19 | ## stdio
775 | 20 |
776 | 21 | In the **stdio** transport:
777 | 22 |
778 | 23 | - The client launches the MCP server as a subprocess.
779 | 24 | - The server receives JSON-RPC messages on its standard input (`stdin`) and writes
780 | 25 | responses to its standard output (`stdout`).
781 | 26 | - Messages are delimited by newlines, and **MUST NOT** contain embedded newlines.
782 | 27 | - The server **MAY** write UTF-8 strings to its standard error (`stderr`) for logging
783 | 28 | purposes. Clients **MAY** capture, forward, or ignore this logging.
784 | 29 | - The server **MUST NOT** write anything to its `stdout` that is not a valid MCP message.
785 | 30 | - The client **MUST NOT** write anything to the server's `stdin` that is not a valid MCP
786 | 31 | message.
787 | 32 |
788 | 33 | ```mermaid
789 | 34 | sequenceDiagram
790 | 35 | participant Client
791 | 36 | participant Server Process
792 | 37 |
793 | 38 | Client->>+Server Process: Launch subprocess
794 | 39 | loop Message Exchange
795 | 40 | Client->>Server Process: Write to stdin
796 | 41 | Server Process->>Client: Write to stdout
797 | 42 | Server Process--)Client: Optional logs on stderr
798 | 43 | end
799 | 44 | Client->>Server Process: Close stdin, terminate subprocess
800 | 45 | deactivate Server Process
801 | 46 | ```
802 | 47 |
803 | 48 | ## HTTP with SSE
804 | 49 |
805 | 50 | In the **SSE** transport, the server operates as an independent process that can handle
806 | 51 | multiple client connections.
807 | 52 |
808 | 53 | The server **MUST** provide two endpoints:
809 | 54 |
810 | 55 | 1. An SSE endpoint, for clients to establish a connection and receive messages from the
811 | 56 | server
812 | 57 | 2. A regular HTTP POST endpoint for clients to send messages to the server
813 | 58 |
814 | 59 | When a client connects, the server **MUST** send an `endpoint` event containing a URI for
815 | 60 | the client to use for sending messages. All subsequent client messages **MUST** be sent
816 | 61 | as HTTP POST requests to this endpoint.
817 | 62 |
818 | 63 | Server messages are sent as SSE `message` events, with the message content encoded as
819 | 64 | JSON in the event data.
820 | 65 |
821 | 66 | ```mermaid
822 | 67 | sequenceDiagram
823 | 68 | participant Client
824 | 69 | participant Server
825 | 70 |
826 | 71 | Client->>Server: Open SSE connection
827 | 72 | Server->>Client: endpoint event
828 | 73 | loop Message Exchange
829 | 74 | Client->>Server: HTTP POST messages
830 | 75 | Server->>Client: SSE message events
831 | 76 | end
832 | 77 | Client->>Server: Close SSE connection
833 | 78 | ```
834 | 79 |
835 | 80 | ## Custom Transports
836 | 81 |
837 | 82 | Clients and servers **MAY** implement additional custom transport mechanisms to suit
838 | 83 | their specific needs. The protocol is transport-agnostic and can be implemented over any
839 | 84 | communication channel that supports bidirectional message exchange.
840 | 85 |
841 | 86 | Implementers who choose to support custom transports **MUST** ensure they preserve the
842 | 87 | JSON-RPC message format and lifecycle requirements defined by MCP. Custom transports
843 | 88 | **SHOULD** document their specific connection establishment and message exchange patterns
844 | 89 | to aid interoperability.
845 | 90 |
846 |
847 |
848 | --------------------------------------------------------------------------------
849 | /docs/specification/2024-11-05/basic/utilities/_index.md:
850 | --------------------------------------------------------------------------------
851 | 1 | ---
852 | 2 | title: Utilities
853 | 3 | ---
854 | 4 |
855 | 5 | {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
856 | 6 |
857 | 7 | These optional features enhance the base protocol functionality with various utilities.
858 | 8 |
859 | 9 | {{< cards >}} {{< card link="ping" title="Ping" icon="status-online" >}}
860 | 10 | {{< card link="cancellation" title="Cancellation" icon="x" >}}
861 | 11 | {{< card link="progress" title="Progress" icon="clock" >}} {{< /cards >}}
862 | 12 |
863 |
864 |
865 | --------------------------------------------------------------------------------
866 | /docs/specification/2024-11-05/basic/utilities/cancellation.md:
867 | --------------------------------------------------------------------------------
868 | 1 | ---
869 | 2 | title: Cancellation
870 | 3 | weight: 10
871 | 4 | ---
872 | 5 |
873 | 6 | {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
874 | 7 |
875 | 8 | The Model Context Protocol (MCP) supports optional cancellation of in-progress requests
876 | 9 | through notification messages. Either side can send a cancellation notification to
877 | 10 | indicate that a previously-issued request should be terminated.
878 | 11 |
879 | 12 | ## Cancellation Flow
880 | 13 |
881 | 14 | When a party wants to cancel an in-progress request, it sends a `notifications/cancelled`
882 | 15 | notification containing:
883 | 16 |
884 | 17 | - The ID of the request to cancel
885 | 18 | - An optional reason string that can be logged or displayed
886 | 19 |
887 | 20 | ```json
888 | 21 | {
889 | 22 | "jsonrpc": "2.0",
890 | 23 | "method": "notifications/cancelled",
891 | 24 | "params": {
892 | 25 | "requestId": "123",
893 | 26 | "reason": "User requested cancellation"
894 | 27 | }
895 | 28 | }
896 | 29 | ```
897 | 30 |
898 | 31 | ## Behavior Requirements
899 | 32 |
900 | 33 | 1. Cancellation notifications **MUST** only reference requests that:
901 | 34 | - Were previously issued in the same direction
902 | 35 | - Are believed to still be in-progress
903 | 36 | 2. The `initialize` request **MUST NOT** be cancelled by clients
904 | 37 | 3. Receivers of cancellation notifications **SHOULD**:
905 | 38 | - Stop processing the cancelled request
906 | 39 | - Free associated resources
907 | 40 | - Not send a response for the cancelled request
908 | 41 | 4. Receivers **MAY** ignore cancellation notifications if:
909 | 42 | - The referenced request is unknown
910 | 43 | - Processing has already completed
911 | 44 | - The request cannot be cancelled
912 | 45 | 5. The sender of the cancellation notification **SHOULD** ignore any response to the
913 | 46 | request that arrives afterward
914 | 47 |
915 | 48 | ## Timing Considerations
916 | 49 |
917 | 50 | Due to network latency, cancellation notifications may arrive after request processing
918 | 51 | has completed, and potentially after a response has already been sent.
919 | 52 |
920 | 53 | Both parties **MUST** handle these race conditions gracefully:
921 | 54 |
922 | 55 | ```mermaid
923 | 56 | sequenceDiagram
924 | 57 | participant Client
925 | 58 | participant Server
926 | 59 |
927 | 60 | Client->>Server: Request (ID: 123)
928 | 61 | Note over Server: Processing starts
929 | 62 | Client--)Server: notifications/cancelled (ID: 123)
930 | 63 | alt
931 | 64 | Note over Server: Processing may have<br/>completed before<br/>cancellation arrives
932 | 65 | else If not completed
933 | 66 | Note over Server: Stop processing
934 | 67 | end
935 | 68 | ```
936 | 69 |
937 | 70 | ## Implementation Notes
938 | 71 |
939 | 72 | - Both parties **SHOULD** log cancellation reasons for debugging
940 | 73 | - Application UIs **SHOULD** indicate when cancellation is requested
941 | 74 |
942 | 75 | ## Error Handling
943 | 76 |
944 | 77 | Invalid cancellation notifications **SHOULD** be ignored:
945 | 78 |
946 | 79 | - Unknown request IDs
947 | 80 | - Already completed requests
948 | 81 | - Malformed notifications
949 | 82 |
950 | 83 | This maintains the "fire and forget" nature of notifications while allowing for race
951 | 84 | conditions in asynchronous communication.
952 | 85 |
953 |
954 |
955 | --------------------------------------------------------------------------------
956 | /docs/specification/2024-11-05/basic/utilities/ping.md:
957 | --------------------------------------------------------------------------------
958 | 1 | ---
959 | 2 | title: Ping
960 | 3 | weight: 5
961 | 4 | ---
962 | 5 |
963 | 6 | {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
964 | 7 |
965 | 8 | The Model Context Protocol includes an optional ping mechanism that allows either party
966 | 9 | to verify that their counterpart is still responsive and the connection is alive.
967 | 10 |
968 | 11 | ## Overview
969 | 12 |
970 | 13 | The ping functionality is implemented through a simple request/response pattern. Either
971 | 14 | the client or server can initiate a ping by sending a `ping` request.
972 | 15 |
973 | 16 | ## Message Format
974 | 17 |
975 | 18 | A ping request is a standard JSON-RPC request with no parameters:
976 | 19 |
977 | 20 | ```json
978 | 21 | {
979 | 22 | "jsonrpc": "2.0",
980 | 23 | "id": "123",
981 | 24 | "method": "ping"
982 | 25 | }
983 | 26 | ```
984 | 27 |
985 | 28 | ## Behavior Requirements
986 | 29 |
987 | 30 | 1. The receiver **MUST** respond promptly with an empty response:
988 | 31 |
989 | 32 | ```json
990 | 33 | {
991 | 34 | "jsonrpc": "2.0",
992 | 35 | "id": "123",
993 | 36 | "result": {}
994 | 37 | }
995 | 38 | ```
996 | 39 |
997 | 40 | 2. If no response is received within a reasonable timeout period, the sender **MAY**:
998 | 41 | - Consider the connection stale
999 | 42 | - Terminate the connection
1000 | 43 | - Attempt reconnection procedures
1001 | 44 |
1002 | 45 | ## Usage Patterns
1003 | 46 |
1004 | 47 | ```mermaid
1005 | 48 | sequenceDiagram
1006 | 49 | participant Sender
1007 | 50 | participant Receiver
1008 | 51 |
1009 | 52 | Sender->>Receiver: ping request
1010 | 53 | Receiver->>Sender: empty response
1011 | 54 | ```
1012 | 55 |
1013 | 56 | ## Implementation Considerations
1014 | 57 |
1015 | 58 | - Implementations **SHOULD** periodically issue pings to detect connection health
1016 | 59 | - The frequency of pings **SHOULD** be configurable
1017 | 60 | - Timeouts **SHOULD** be appropriate for the network environment
1018 | 61 | - Excessive pinging **SHOULD** be avoided to reduce network overhead
1019 | 62 |
1020 | 63 | ## Error Handling
1021 | 64 |
1022 | 65 | - Timeouts **SHOULD** be treated as connection failures
1023 | 66 | - Multiple failed pings **MAY** trigger connection reset
1024 | 67 | - Implementations **SHOULD** log ping failures for diagnostics
1025 | 68 |
1026 |
1027 |
1028 | --------------------------------------------------------------------------------
1029 | /docs/specification/2024-11-05/basic/utilities/progress.md:
1030 | --------------------------------------------------------------------------------
1031 | 1 | ---
1032 | 2 | title: Progress
1033 | 3 | weight: 30
1034 | 4 | ---
1035 | 5 |
1036 | 6 | {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
1037 | 7 |
1038 | 8 | The Model Context Protocol (MCP) supports optional progress tracking for long-running
1039 | 9 | operations through notification messages. Either side can send progress notifications to
1040 | 10 | provide updates about operation status.
1041 | 11 |
1042 | 12 | ## Progress Flow
1043 | 13 |
1044 | 14 | When a party wants to _receive_ progress updates for a request, it includes a
1045 | 15 | `progressToken` in the request metadata.
1046 | 16 |
1047 | 17 | - Progress tokens **MUST** be a string or integer value
1048 | 18 | - Progress tokens can be chosen by the sender using any means, but **MUST** be unique
1049 | 19 | across all active requests.
1050 | 20 |
1051 | 21 | ```json
1052 | 22 | {
1053 | 23 | "jsonrpc": "2.0",
1054 | 24 | "id": 1,
1055 | 25 | "method": "some_method",
1056 | 26 | "params": {
1057 | 27 | "_meta": {
1058 | 28 | "progressToken": "abc123"
1059 | 29 | }
1060 | 30 | }
1061 | 31 | }
1062 | 32 | ```
1063 | 33 |
1064 | 34 | The receiver **MAY** then send progress notifications containing:
1065 | 35 |
1066 | 36 | - The original progress token
1067 | 37 | - The current progress value so far
1068 | 38 | - An optional "total" value
1069 | 39 |
1070 | 40 | ```json
1071 | 41 | {
1072 | 42 | "jsonrpc": "2.0",
1073 | 43 | "method": "notifications/progress",
1074 | 44 | "params": {
1075 | 45 | "progressToken": "abc123",
1076 | 46 | "progress": 50,
1077 | 47 | "total": 100
1078 | 48 | }
1079 | 49 | }
1080 | 50 | ```
1081 | 51 |
1082 | 52 | - The `progress` value **MUST** increase with each notification, even if the total is
1083 | 53 | unknown.
1084 | 54 | - The `progress` and the `total` values **MAY** be floating point.
1085 | 55 |
1086 | 56 | ## Behavior Requirements
1087 | 57 |
1088 | 58 | 1. Progress notifications **MUST** only reference tokens that:
1089 | 59 |
1090 | 60 | - Were provided in an active request
1091 | 61 | - Are associated with an in-progress operation
1092 | 62 |
1093 | 63 | 2. Receivers of progress requests **MAY**:
1094 | 64 | - Choose not to send any progress notifications
1095 | 65 | - Send notifications at whatever frequency they deem appropriate
1096 | 66 | - Omit the total value if unknown
1097 | 67 |
1098 | 68 | ```mermaid
1099 | 69 | sequenceDiagram
1100 | 70 | participant Sender
1101 | 71 | participant Receiver
1102 | 72 |
1103 | 73 | Note over Sender,Receiver: Request with progress token
1104 | 74 | Sender->>Receiver: Method request with progressToken
1105 | 75 |
1106 | 76 | Note over Sender,Receiver: Progress updates
1107 | 77 | loop Progress Updates
1108 | 78 | Receiver-->>Sender: Progress notification (0.2/1.0)
1109 | 79 | Receiver-->>Sender: Progress notification (0.6/1.0)
1110 | 80 | Receiver-->>Sender: Progress notification (1.0/1.0)
1111 | 81 | end
1112 | 82 |
1113 | 83 | Note over Sender,Receiver: Operation complete
1114 | 84 | Receiver->>Sender: Method response
1115 | 85 | ```
1116 | 86 |
1117 | 87 | ## Implementation Notes
1118 | 88 |
1119 | 89 | - Senders and receivers **SHOULD** track active progress tokens
1120 | 90 | - Both parties **SHOULD** implement rate limiting to prevent flooding
1121 | 91 | - Progress notifications **MUST** stop after completion
1122 | 92 |
1123 |
1124 |
1125 | --------------------------------------------------------------------------------
1126 | /docs/specification/2024-11-05/client/_index.md:
1127 | --------------------------------------------------------------------------------
1128 | 1 | ---
1129 | 2 | title: Client Features
1130 | 3 | cascade:
1131 | 4 | type: docs
1132 | 5 | weight: 4
1133 | 6 | ---
1134 | 7 |
1135 | 8 | {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
1136 | 9 |
1137 | 10 | Clients can implement additional features to enrich connected MCP servers:
1138 | 11 |
1139 | 12 | {{< cards >}} {{< card link="roots" title="Roots" icon="folder" >}}
1140 | 13 | {{< card link="sampling" title="Sampling" icon="annotation" >}} {{< /cards >}}
1141 | 14 |
1142 |
1143 |
1144 | --------------------------------------------------------------------------------
1145 | /docs/specification/2024-11-05/client/roots.md:
1146 | --------------------------------------------------------------------------------
1147 | 1 | ---
1148 | 2 | title: Roots
1149 | 3 | type: docs
1150 | 4 | weight: 40
1151 | 5 | ---
1152 | 6 |
1153 | 7 | {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
1154 | 8 |
1155 | 9 | The Model Context Protocol (MCP) provides a standardized way for clients to expose
1156 | 10 | filesystem "roots" to servers. Roots define the boundaries of where servers can operate
1157 | 11 | within the filesystem, allowing them to understand which directories and files they have
1158 | 12 | access to. Servers can request the list of roots from supporting clients and receive
1159 | 13 | notifications when that list changes.
1160 | 14 |
1161 | 15 | ## User Interaction Model
1162 | 16 |
1163 | 17 | Roots in MCP are typically exposed through workspace or project configuration interfaces.
1164 | 18 |
1165 | 19 | For example, implementations could offer a workspace/project picker that allows users to
1166 | 20 | select directories and files the server should have access to. This can be combined with
1167 | 21 | automatic workspace detection from version control systems or project files.
1168 | 22 |
1169 | 23 | However, implementations are free to expose roots through any interface pattern that
1170 | 24 | suits their needs—the protocol itself does not mandate any specific user
1171 | 25 | interaction model.
1172 | 26 |
1173 | 27 | ## Capabilities
1174 | 28 |
1175 | 29 | Clients that support roots **MUST** declare the `roots` capability during
1176 | 30 | [initialization]({{< ref "/specification/2024-11-05/basic/lifecycle#initialization" >}}):
1177 | 31 |
1178 | 32 | ```json
1179 | 33 | {
1180 | 34 | "capabilities": {
1181 | 35 | "roots": {
1182 | 36 | "listChanged": true
1183 | 37 | }
1184 | 38 | }
1185 | 39 | }
1186 | 40 | ```
1187 | 41 |
1188 | 42 | `listChanged` indicates whether the client will emit notifications when the list of roots
1189 | 43 | changes.
1190 | 44 |
1191 | 45 | ## Protocol Messages
1192 | 46 |
1193 | 47 | ### Listing Roots
1194 | 48 |
1195 | 49 | To retrieve roots, servers send a `roots/list` request:
1196 | 50 |
1197 | 51 | **Request:**
1198 | 52 |
1199 | 53 | ```json
1200 | 54 | {
1201 | 55 | "jsonrpc": "2.0",
1202 | 56 | "id": 1,
1203 | 57 | "method": "roots/list"
1204 | 58 | }
1205 | 59 | ```
1206 | 60 |
1207 | 61 | **Response:**
1208 | 62 |
1209 | 63 | ```json
1210 | 64 | {
1211 | 65 | "jsonrpc": "2.0",
1212 | 66 | "id": 1,
1213 | 67 | "result": {
1214 | 68 | "roots": [
1215 | 69 | {
1216 | 70 | "uri": "file:///home/user/projects/myproject",
1217 | 71 | "name": "My Project"
1218 | 72 | }
1219 | 73 | ]
1220 | 74 | }
1221 | 75 | }
1222 | 76 | ```
1223 | 77 |
1224 | 78 | ### Root List Changes
1225 | 79 |
1226 | 80 | When roots change, clients that support `listChanged` **MUST** send a notification:
1227 | 81 |
1228 | 82 | ```json
1229 | 83 | {
1230 | 84 | "jsonrpc": "2.0",
1231 | 85 | "method": "notifications/roots/list_changed"
1232 | 86 | }
1233 | 87 | ```
1234 | 88 |
1235 | 89 | ## Message Flow
1236 | 90 |
1237 | 91 | ```mermaid
1238 | 92 | sequenceDiagram
1239 | 93 | participant Server
1240 | 94 | participant Client
1241 | 95 |
1242 | 96 | Note over Server,Client: Discovery
1243 | 97 | Server->>Client: roots/list
1244 | 98 | Client-->>Server: Available roots
1245 | 99 |
1246 | 100 | Note over Server,Client: Changes
1247 | 101 | Client--)Server: notifications/roots/list_changed
1248 | 102 | Server->>Client: roots/list
1249 | 103 | Client-->>Server: Updated roots
1250 | 104 | ```
1251 | 105 |
1252 | 106 | ## Data Types
1253 | 107 |
1254 | 108 | ### Root
1255 | 109 |
1256 | 110 | A root definition includes:
1257 | 111 |
1258 | 112 | - `uri`: Unique identifier for the root. This **MUST** be a `file://` URI in the current
1259 | 113 | specification.
1260 | 114 | - `name`: Optional human-readable name for display purposes.
1261 | 115 |
1262 | 116 | Example roots for different use cases:
1263 | 117 |
1264 | 118 | #### Project Directory
1265 | 119 |
1266 | 120 | ```json
1267 | 121 | {
1268 | 122 | "uri": "file:///home/user/projects/myproject",
1269 | 123 | "name": "My Project"
1270 | 124 | }
1271 | 125 | ```
1272 | 126 |
1273 | 127 | #### Multiple Repositories
1274 | 128 |
1275 | 129 | ```json
1276 | 130 | [
1277 | 131 | {
1278 | 132 | "uri": "file:///home/user/repos/frontend",
1279 | 133 | "name": "Frontend Repository"
1280 | 134 | },
1281 | 135 | {
1282 | 136 | "uri": "file:///home/user/repos/backend",
1283 | 137 | "name": "Backend Repository"
1284 | 138 | }
1285 | 139 | ]
1286 | 140 | ```
1287 | 141 |
1288 | 142 | ## Error Handling
1289 | 143 |
1290 | 144 | Clients **SHOULD** return standard JSON-RPC errors for common failure cases:
1291 | 145 |
1292 | 146 | - Client does not support roots: `-32601` (Method not found)
1293 | 147 | - Internal errors: `-32603`
1294 | 148 |
1295 | 149 | Example error:
1296 | 150 |
1297 | 151 | ```json
1298 | 152 | {
1299 | 153 | "jsonrpc": "2.0",
1300 | 154 | "id": 1,
1301 | 155 | "error": {
1302 | 156 | "code": -32601,
1303 | 157 | "message": "Roots not supported",
1304 | 158 | "data": {
1305 | 159 | "reason": "Client does not have roots capability"
1306 | 160 | }
1307 | 161 | }
1308 | 162 | }
1309 | 163 | ```
1310 | 164 |
1311 | 165 | ## Security Considerations
1312 | 166 |
1313 | 167 | 1. Clients **MUST**:
1314 | 168 |
1315 | 169 | - Only expose roots with appropriate permissions
1316 | 170 | - Validate all root URIs to prevent path traversal
1317 | 171 | - Implement proper access controls
1318 | 172 | - Monitor root accessibility
1319 | 173 |
1320 | 174 | 2. Servers **SHOULD**:
1321 | 175 | - Handle cases where roots become unavailable
1322 | 176 | - Respect root boundaries during operations
1323 | 177 | - Validate all paths against provided roots
1324 | 178 |
1325 | 179 | ## Implementation Guidelines
1326 | 180 |
1327 | 181 | 1. Clients **SHOULD**:
1328 | 182 |
1329 | 183 | - Prompt users for consent before exposing roots to servers
1330 | 184 | - Provide clear user interfaces for root management
1331 | 185 | - Validate root accessibility before exposing
1332 | 186 | - Monitor for root changes
1333 | 187 |
1334 | 188 | 2. Servers **SHOULD**:
1335 | 189 | - Check for roots capability before usage
1336 | 190 | - Handle root list changes gracefully
1337 | 191 | - Respect root boundaries in operations
1338 | 192 | - Cache root information appropriately
1339 | 193 |
1340 |
1341 |
1342 | --------------------------------------------------------------------------------
1343 | /docs/specification/2024-11-05/client/sampling.md:
1344 | --------------------------------------------------------------------------------
1345 | 1 | ---
1346 | 2 | title: Sampling
1347 | 3 | type: docs
1348 | 4 | weight: 40
1349 | 5 | ---
1350 | 6 |
1351 | 7 | {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
1352 | 8 |
1353 | 9 | The Model Context Protocol (MCP) provides a standardized way for servers to request LLM
1354 | 10 | sampling ("completions" or "generations") from language models via clients. This flow
1355 | 11 | allows clients to maintain control over model access, selection, and permissions while
1356 | 12 | enabling servers to leverage AI capabilities—with no server API keys necessary.
1357 | 13 | Servers can request text or image-based interactions and optionally include context from
1358 | 14 | MCP servers in their prompts.
1359 | 15 |
1360 | 16 | ## User Interaction Model
1361 | 17 |
1362 | 18 | Sampling in MCP allows servers to implement agentic behaviors, by enabling LLM calls to
1363 | 19 | occur _nested_ inside other MCP server features.
1364 | 20 |
1365 | 21 | Implementations are free to expose sampling through any interface pattern that suits
1366 | 22 | their needs—the protocol itself does not mandate any specific user interaction
1367 | 23 | model.
1368 | 24 |
1369 | 25 | {{< callout type="warning" >}} For trust & safety and security, there **SHOULD** always
1370 | 26 | be a human in the loop with the ability to deny sampling requests.
1371 | 27 |
1372 | 28 | Applications **SHOULD**:
1373 | 29 |
1374 | 30 | - Provide UI that makes it easy and intuitive to review sampling requests
1375 | 31 | - Allow users to view and edit prompts before sending
1376 | 32 | - Present generated responses for review before delivery {{< /callout >}}
1377 | 33 |
1378 | 34 | ## Capabilities
1379 | 35 |
1380 | 36 | Clients that support sampling **MUST** declare the `sampling` capability during
1381 | 37 | [initialization]({{< ref "/specification/2024-11-05/basic/lifecycle#initialization" >}}):
1382 | 38 |
1383 | 39 | ```json
1384 | 40 | {
1385 | 41 | "capabilities": {
1386 | 42 | "sampling": {}
1387 | 43 | }
1388 | 44 | }
1389 | 45 | ```
1390 | 46 |
1391 | 47 | ## Protocol Messages
1392 | 48 |
1393 | 49 | ### Creating Messages
1394 | 50 |
1395 | 51 | To request a language model generation, servers send a `sampling/createMessage` request:
1396 | 52 |
1397 | 53 | **Request:**
1398 | 54 |
1399 | 55 | ```json
1400 | 56 | {
1401 | 57 | "jsonrpc": "2.0",
1402 | 58 | "id": 1,
1403 | 59 | "method": "sampling/createMessage",
1404 | 60 | "params": {
1405 | 61 | "messages": [
1406 | 62 | {
1407 | 63 | "role": "user",
1408 | 64 | "content": {
1409 | 65 | "type": "text",
1410 | 66 | "text": "What is the capital of France?"
1411 | 67 | }
1412 | 68 | }
1413 | 69 | ],
1414 | 70 | "modelPreferences": {
1415 | 71 | "hints": [
1416 | 72 | {
1417 | 73 | "name": "claude-3-sonnet"
1418 | 74 | }
1419 | 75 | ],
1420 | 76 | "intelligencePriority": 0.8,
1421 | 77 | "speedPriority": 0.5
1422 | 78 | },
1423 | 79 | "systemPrompt": "You are a helpful assistant.",
1424 | 80 | "maxTokens": 100
1425 | 81 | }
1426 | 82 | }
1427 | 83 | ```
1428 | 84 |
1429 | 85 | **Response:**
1430 | 86 |
1431 | 87 | ```json
1432 | 88 | {
1433 | 89 | "jsonrpc": "2.0",
1434 | 90 | "id": 1,
1435 | 91 | "result": {
1436 | 92 | "role": "assistant",
1437 | 93 | "content": {
1438 | 94 | "type": "text",
1439 | 95 | "text": "The capital of France is Paris."
1440 | 96 | },
1441 | 97 | "model": "claude-3-sonnet-20240307",
1442 | 98 | "stopReason": "endTurn"
1443 | 99 | }
1444 | 100 | }
1445 | 101 | ```
1446 | 102 |
1447 | 103 | ## Message Flow
1448 | 104 |
1449 | 105 | ```mermaid
1450 | 106 | sequenceDiagram
1451 | 107 | participant Server
1452 | 108 | participant Client
1453 | 109 | participant User
1454 | 110 | participant LLM
1455 | 111 |
1456 | 112 | Note over Server,Client: Server initiates sampling
1457 | 113 | Server->>Client: sampling/createMessage
1458 | 114 |
1459 | 115 | Note over Client,User: Human-in-the-loop review
1460 | 116 | Client->>User: Present request for approval
1461 | 117 | User-->>Client: Review and approve/modify
1462 | 118 |
1463 | 119 | Note over Client,LLM: Model interaction
1464 | 120 | Client->>LLM: Forward approved request
1465 | 121 | LLM-->>Client: Return generation
1466 | 122 |
1467 | 123 | Note over Client,User: Response review
1468 | 124 | Client->>User: Present response for approval
1469 | 125 | User-->>Client: Review and approve/modify
1470 | 126 |
1471 | 127 | Note over Server,Client: Complete request
1472 | 128 | Client-->>Server: Return approved response
1473 | 129 | ```
1474 | 130 |
1475 | 131 | ## Data Types
1476 | 132 |
1477 | 133 | ### Messages
1478 | 134 |
1479 | 135 | Sampling messages can contain:
1480 | 136 |
1481 | 137 | #### Text Content
1482 | 138 |
1483 | 139 | ```json
1484 | 140 | {
1485 | 141 | "type": "text",
1486 | 142 | "text": "The message content"
1487 | 143 | }
1488 | 144 | ```
1489 | 145 |
1490 | 146 | #### Image Content
1491 | 147 |
1492 | 148 | ```json
1493 | 149 | {
1494 | 150 | "type": "image",
1495 | 151 | "data": "base64-encoded-image-data",
1496 | 152 | "mimeType": "image/jpeg"
1497 | 153 | }
1498 | 154 | ```
1499 | 155 |
1500 | 156 | ### Model Preferences
1501 | 157 |
1502 | 158 | Model selection in MCP requires careful abstraction since servers and clients may use
1503 | 159 | different AI providers with distinct model offerings. A server cannot simply request a
1504 | 160 | specific model by name since the client may not have access to that exact model or may
1505 | 161 | prefer to use a different provider's equivalent model.
1506 | 162 |
1507 | 163 | To solve this, MCP implements a preference system that combines abstract capability
1508 | 164 | priorities with optional model hints:
1509 | 165 |
1510 | 166 | #### Capability Priorities
1511 | 167 |
1512 | 168 | Servers express their needs through three normalized priority values (0-1):
1513 | 169 |
1514 | 170 | - `costPriority`: How important is minimizing costs? Higher values prefer cheaper models.
1515 | 171 | - `speedPriority`: How important is low latency? Higher values prefer faster models.
1516 | 172 | - `intelligencePriority`: How important are advanced capabilities? Higher values prefer
1517 | 173 | more capable models.
1518 | 174 |
1519 | 175 | #### Model Hints
1520 | 176 |
1521 | 177 | While priorities help select models based on characteristics, `hints` allow servers to
1522 | 178 | suggest specific models or model families:
1523 | 179 |
1524 | 180 | - Hints are treated as substrings that can match model names flexibly
1525 | 181 | - Multiple hints are evaluated in order of preference
1526 | 182 | - Clients **MAY** map hints to equivalent models from different providers
1527 | 183 | - Hints are advisory—clients make final model selection
1528 | 184 |
1529 | 185 | For example:
1530 | 186 |
1531 | 187 | ```json
1532 | 188 | {
1533 | 189 | "hints": [
1534 | 190 | { "name": "claude-3-sonnet" }, // Prefer Sonnet-class models
1535 | 191 | { "name": "claude" } // Fall back to any Claude model
1536 | 192 | ],
1537 | 193 | "costPriority": 0.3, // Cost is less important
1538 | 194 | "speedPriority": 0.8, // Speed is very important
1539 | 195 | "intelligencePriority": 0.5 // Moderate capability needs
1540 | 196 | }
1541 | 197 | ```
1542 | 198 |
1543 | 199 | The client processes these preferences to select an appropriate model from its available
1544 | 200 | options. For instance, if the client doesn't have access to Claude models but has Gemini,
1545 | 201 | it might map the sonnet hint to `gemini-1.5-pro` based on similar capabilities.
1546 | 202 |
1547 | 203 | ## Error Handling
1548 | 204 |
1549 | 205 | Clients **SHOULD** return errors for common failure cases:
1550 | 206 |
1551 | 207 | Example error:
1552 | 208 |
1553 | 209 | ```json
1554 | 210 | {
1555 | 211 | "jsonrpc": "2.0",
1556 | 212 | "id": 1,
1557 | 213 | "error": {
1558 | 214 | "code": -1,
1559 | 215 | "message": "User rejected sampling request"
1560 | 216 | }
1561 | 217 | }
1562 | 218 | ```
1563 | 219 |
1564 | 220 | ## Security Considerations
1565 | 221 |
1566 | 222 | 1. Clients **SHOULD** implement user approval controls
1567 | 223 | 2. Both parties **SHOULD** validate message content
1568 | 224 | 3. Clients **SHOULD** respect model preference hints
1569 | 225 | 4. Clients **SHOULD** implement rate limiting
1570 | 226 | 5. Both parties **MUST** handle sensitive data appropriately
1571 | 227 |
1572 |
1573 |
1574 | --------------------------------------------------------------------------------
1575 | /docs/specification/2024-11-05/server/_index.md:
1576 | --------------------------------------------------------------------------------
1577 | 1 | ---
1578 | 2 | title: Server Features
1579 | 3 | cascade:
1580 | 4 | type: docs
1581 | 5 | weight: 3
1582 | 6 | ---
1583 | 7 |
1584 | 8 | {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
1585 | 9 |
1586 | 10 | Servers provide the fundamental building blocks for adding context to language models via
1587 | 11 | MCP. These primitives enable rich interactions between clients, servers, and language
1588 | 12 | models:
1589 | 13 |
1590 | 14 | - **Prompts**: Pre-defined templates or instructions that guide language model
1591 | 15 | interactions
1592 | 16 | - **Resources**: Structured data or content that provides additional context to the model
1593 | 17 | - **Tools**: Executable functions that allow models to perform actions or retrieve
1594 | 18 | information
1595 | 19 |
1596 | 20 | Each primitive can be summarized in the following control hierarchy:
1597 | 21 |
1598 | 22 | | Primitive | Control | Description | Example |
1599 | 23 | | --------- | ---------------------- | -------------------------------------------------- | ------------------------------- |
1600 | 24 | | Prompts | User-controlled | Interactive templates invoked by user choice | Slash commands, menu options |
1601 | 25 | | Resources | Application-controlled | Contextual data attached and managed by the client | File contents, git history |
1602 | 26 | | Tools | Model-controlled | Functions exposed to the LLM to take actions | API POST requests, file writing |
1603 | 27 |
1604 | 28 | Explore these key primitives in more detail below:
1605 | 29 |
1606 | 30 | {{< cards >}} {{< card link="prompts" title="Prompts" icon="chat-alt-2" >}}
1607 | 31 | {{< card link="resources" title="Resources" icon="document" >}}
1608 | 32 | {{< card link="tools" title="Tools" icon="adjustments" >}} {{< /cards >}}
1609 | 33 |
1610 |
1611 |
1612 | --------------------------------------------------------------------------------
1613 | /docs/specification/2024-11-05/server/prompts.md:
1614 | --------------------------------------------------------------------------------
1615 | 1 | ---
1616 | 2 | title: Prompts
1617 | 3 | weight: 10
1618 | 4 | ---
1619 | 5 |
1620 | 6 | {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
1621 | 7 |
1622 | 8 | The Model Context Protocol (MCP) provides a standardized way for servers to expose prompt
1623 | 9 | templates to clients. Prompts allow servers to provide structured messages and
1624 | 10 | instructions for interacting with language models. Clients can discover available
1625 | 11 | prompts, retrieve their contents, and provide arguments to customize them.
1626 | 12 |
1627 | 13 | ## User Interaction Model
1628 | 14 |
1629 | 15 | Prompts are designed to be **user-controlled**, meaning they are exposed from servers to
1630 | 16 | clients with the intention of the user being able to explicitly select them for use.
1631 | 17 |
1632 | 18 | Typically, prompts would be triggered through user-initiated commands in the user
1633 | 19 | interface, which allows users to naturally discover and invoke available prompts.
1634 | 20 |
1635 | 21 | For example, as slash commands:
1636 | 22 |
1637 | 23 | 
1638 | 24 |
1639 | 25 | However, implementors are free to expose prompts through any interface pattern that suits
1640 | 26 | their needs—the protocol itself does not mandate any specific user interaction
1641 | 27 | model.
1642 | 28 |
1643 | 29 | ## Capabilities
1644 | 30 |
1645 | 31 | Servers that support prompts **MUST** declare the `prompts` capability during
1646 | 32 | [initialization]({{< ref "/specification/2024-11-05/basic/lifecycle#initialization" >}}):
1647 | 33 |
1648 | 34 | ```json
1649 | 35 | {
1650 | 36 | "capabilities": {
1651 | 37 | "prompts": {
1652 | 38 | "listChanged": true
1653 | 39 | }
1654 | 40 | }
1655 | 41 | }
1656 | 42 | ```
1657 | 43 |
1658 | 44 | `listChanged` indicates whether the server will emit notifications when the list of
1659 | 45 | available prompts changes.
1660 | 46 |
1661 | 47 | ## Protocol Messages
1662 | 48 |
1663 | 49 | ### Listing Prompts
1664 | 50 |
1665 | 51 | To retrieve available prompts, clients send a `prompts/list` request. This operation
1666 | 52 | supports
1667 | 53 | [pagination]({{< ref "/specification/2024-11-05/server/utilities/pagination" >}}).
1668 | 54 |
1669 | 55 | **Request:**
1670 | 56 |
1671 | 57 | ```json
1672 | 58 | {
1673 | 59 | "jsonrpc": "2.0",
1674 | 60 | "id": 1,
1675 | 61 | "method": "prompts/list",
1676 | 62 | "params": {
1677 | 63 | "cursor": "optional-cursor-value"
1678 | 64 | }
1679 | 65 | }
1680 | 66 | ```
1681 | 67 |
1682 | 68 | **Response:**
1683 | 69 |
1684 | 70 | ```json
1685 | 71 | {
1686 | 72 | "jsonrpc": "2.0",
1687 | 73 | "id": 1,
1688 | 74 | "result": {
1689 | 75 | "prompts": [
1690 | 76 | {
1691 | 77 | "name": "code_review",
1692 | 78 | "description": "Asks the LLM to analyze code quality and suggest improvements",
1693 | 79 | "arguments": [
1694 | 80 | {
1695 | 81 | "name": "code",
1696 | 82 | "description": "The code to review",
1697 | 83 | "required": true
1698 | 84 | }
1699 | 85 | ]
1700 | 86 | }
1701 | 87 | ],
1702 | 88 | "nextCursor": "next-page-cursor"
1703 | 89 | }
1704 | 90 | }
1705 | 91 | ```
1706 | 92 |
1707 | 93 | ### Getting a Prompt
1708 | 94 |
1709 | 95 | To retrieve a specific prompt, clients send a `prompts/get` request. Arguments may be
1710 | 96 | auto-completed through [the completion
1711 | 97 | API]({{< ref "/specification/2024-11-05/server/utilities/completion" >}}).
1712 | 98 |
1713 | 99 | **Request:**
1714 | 100 |
1715 | 101 | ```json
1716 | 102 | {
1717 | 103 | "jsonrpc": "2.0",
1718 | 104 | "id": 2,
1719 | 105 | "method": "prompts/get",
1720 | 106 | "params": {
1721 | 107 | "name": "code_review",
1722 | 108 | "arguments": {
1723 | 109 | "code": "def hello():\n print('world')"
1724 | 110 | }
1725 | 111 | }
1726 | 112 | }
1727 | 113 | ```
1728 | 114 |
1729 | 115 | **Response:**
1730 | 116 |
1731 | 117 | ```json
1732 | 118 | {
1733 | 119 | "jsonrpc": "2.0",
1734 | 120 | "id": 2,
1735 | 121 | "result": {
1736 | 122 | "description": "Code review prompt",
1737 | 123 | "messages": [
1738 | 124 | {
1739 | 125 | "role": "user",
1740 | 126 | "content": {
1741 | 127 | "type": "text",
1742 | 128 | "text": "Please review this Python code:\ndef hello():\n print('world')"
1743 | 129 | }
1744 | 130 | }
1745 | 131 | ]
1746 | 132 | }
1747 | 133 | }
1748 | 134 | ```
1749 | 135 |
1750 | 136 | ### List Changed Notification
1751 | 137 |
1752 | 138 | When the list of available prompts changes, servers that declared the `listChanged`
1753 | 139 | capability **SHOULD** send a notification:
1754 | 140 |
1755 | 141 | ```json
1756 | 142 | {
1757 | 143 | "jsonrpc": "2.0",
1758 | 144 | "method": "notifications/prompts/list_changed"
1759 | 145 | }
1760 | 146 | ```
1761 | 147 |
1762 | 148 | ## Message Flow
1763 | 149 |
1764 | 150 | ```mermaid
1765 | 151 | sequenceDiagram
1766 | 152 | participant Client
1767 | 153 | participant Server
1768 | 154 |
1769 | 155 | Note over Client,Server: Discovery
1770 | 156 | Client->>Server: prompts/list
1771 | 157 | Server-->>Client: List of prompts
1772 | 158 |
1773 | 159 | Note over Client,Server: Usage
1774 | 160 | Client->>Server: prompts/get
1775 | 161 | Server-->>Client: Prompt content
1776 | 162 |
1777 | 163 | opt listChanged
1778 | 164 | Note over Client,Server: Changes
1779 | 165 | Server--)Client: prompts/list_changed
1780 | 166 | Client->>Server: prompts/list
1781 | 167 | Server-->>Client: Updated prompts
1782 | 168 | end
1783 | 169 | ```
1784 | 170 |
1785 | 171 | ## Data Types
1786 | 172 |
1787 | 173 | ### Prompt
1788 | 174 |
1789 | 175 | A prompt definition includes:
1790 | 176 |
1791 | 177 | - `name`: Unique identifier for the prompt
1792 | 178 | - `description`: Optional human-readable description
1793 | 179 | - `arguments`: Optional list of arguments for customization
1794 | 180 |
1795 | 181 | ### PromptMessage
1796 | 182 |
1797 | 183 | Messages in a prompt can contain:
1798 | 184 |
1799 | 185 | - `role`: Either "user" or "assistant" to indicate the speaker
1800 | 186 | - `content`: One of the following content types:
1801 | 187 |
1802 | 188 | #### Text Content
1803 | 189 |
1804 | 190 | Text content represents plain text messages:
1805 | 191 |
1806 | 192 | ```json
1807 | 193 | {
1808 | 194 | "type": "text",
1809 | 195 | "text": "The text content of the message"
1810 | 196 | }
1811 | 197 | ```
1812 | 198 |
1813 | 199 | This is the most common content type used for natural language interactions.
1814 | 200 |
1815 | 201 | #### Image Content
1816 | 202 |
1817 | 203 | Image content allows including visual information in messages:
1818 | 204 |
1819 | 205 | ```json
1820 | 206 | {
1821 | 207 | "type": "image",
1822 | 208 | "data": "base64-encoded-image-data",
1823 | 209 | "mimeType": "image/png"
1824 | 210 | }
1825 | 211 | ```
1826 | 212 |
1827 | 213 | The image data **MUST** be base64-encoded and include a valid MIME type. This enables
1828 | 214 | multi-modal interactions where visual context is important.
1829 | 215 |
1830 | 216 | #### Embedded Resources
1831 | 217 |
1832 | 218 | Embedded resources allow referencing server-side resources directly in messages:
1833 | 219 |
1834 | 220 | ```json
1835 | 221 | {
1836 | 222 | "type": "resource",
1837 | 223 | "resource": {
1838 | 224 | "uri": "resource://example",
1839 | 225 | "mimeType": "text/plain",
1840 | 226 | "text": "Resource content"
1841 | 227 | }
1842 | 228 | }
1843 | 229 | ```
1844 | 230 |
1845 | 231 | Resources can contain either text or binary (blob) data and **MUST** include:
1846 | 232 |
1847 | 233 | - A valid resource URI
1848 | 234 | - The appropriate MIME type
1849 | 235 | - Either text content or base64-encoded blob data
1850 | 236 |
1851 | 237 | Embedded resources enable prompts to seamlessly incorporate server-managed content like
1852 | 238 | documentation, code samples, or other reference materials directly into the conversation
1853 | 239 | flow.
1854 | 240 |
1855 | 241 | ## Error Handling
1856 | 242 |
1857 | 243 | Servers **SHOULD** return standard JSON-RPC errors for common failure cases:
1858 | 244 |
1859 | 245 | - Invalid prompt name: `-32602` (Invalid params)
1860 | 246 | - Missing required arguments: `-32602` (Invalid params)
1861 | 247 | - Internal errors: `-32603` (Internal error)
1862 | 248 |
1863 | 249 | ## Implementation Considerations
1864 | 250 |
1865 | 251 | 1. Servers **SHOULD** validate prompt arguments before processing
1866 | 252 | 2. Clients **SHOULD** handle pagination for large prompt lists
1867 | 253 | 3. Both parties **SHOULD** respect capability negotiation
1868 | 254 |
1869 | 255 | ## Security
1870 | 256 |
1871 | 257 | Implementations **MUST** carefully validate all prompt inputs and outputs to prevent
1872 | 258 | injection attacks or unauthorized access to resources.
1873 | 259 |
1874 |
1875 |
1876 | --------------------------------------------------------------------------------
1877 | /docs/specification/2024-11-05/server/resource-picker.png:
1878 | --------------------------------------------------------------------------------
1879 | https://raw.githubusercontent.com/modelcontextprotocol/specification/main/docs/specification/2024-11-05/server/resource-picker.png
1880 |
1881 |
1882 | --------------------------------------------------------------------------------
1883 | /docs/specification/2024-11-05/server/resources.md:
1884 | --------------------------------------------------------------------------------
1885 | 1 | ---
1886 | 2 | title: Resources
1887 | 3 | type: docs
1888 | 4 | weight: 20
1889 | 5 | ---
1890 | 6 |
1891 | 7 | {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
1892 | 8 |
1893 | 9 | The Model Context Protocol (MCP) provides a standardized way for servers to expose
1894 | 10 | resources to clients. Resources allow servers to share data that provides context to
1895 | 11 | language models, such as files, database schemas, or application-specific information.
1896 | 12 | Each resource is uniquely identified by a
1897 | 13 | [URI](https://datatracker.ietf.org/doc/html/rfc3986).
1898 | 14 |
1899 | 15 | ## User Interaction Model
1900 | 16 |
1901 | 17 | Resources in MCP are designed to be **application-driven**, with host applications
1902 | 18 | determining how to incorporate context based on their needs.
1903 | 19 |
1904 | 20 | For example, applications could:
1905 | 21 |
1906 | 22 | - Expose resources through UI elements for explicit selection, in a tree or list view
1907 | 23 | - Allow the user to search through and filter available resources
1908 | 24 | - Implement automatic context inclusion, based on heuristics or the AI model's selection
1909 | 25 |
1910 | 26 | 
1911 | 27 |
1912 | 28 | However, implementations are free to expose resources through any interface pattern that
1913 | 29 | suits their needs—the protocol itself does not mandate any specific user
1914 | 30 | interaction model.
1915 | 31 |
1916 | 32 | ## Capabilities
1917 | 33 |
1918 | 34 | Servers that support resources **MUST** declare the `resources` capability:
1919 | 35 |
1920 | 36 | ```json
1921 | 37 | {
1922 | 38 | "capabilities": {
1923 | 39 | "resources": {
1924 | 40 | "subscribe": true,
1925 | 41 | "listChanged": true
1926 | 42 | }
1927 | 43 | }
1928 | 44 | }
1929 | 45 | ```
1930 | 46 |
1931 | 47 | The capability supports two optional features:
1932 | 48 |
1933 | 49 | - `subscribe`: whether the client can subscribe to be notified of changes to individual
1934 | 50 | resources.
1935 | 51 | - `listChanged`: whether the server will emit notifications when the list of available
1936 | 52 | resources changes.
1937 | 53 |
1938 | 54 | Both `subscribe` and `listChanged` are optional—servers can support neither,
1939 | 55 | either, or both:
1940 | 56 |
1941 | 57 | ```json
1942 | 58 | {
1943 | 59 | "capabilities": {
1944 | 60 | "resources": {} // Neither feature supported
1945 | 61 | }
1946 | 62 | }
1947 | 63 | ```
1948 | 64 |
1949 | 65 | ```json
1950 | 66 | {
1951 | 67 | "capabilities": {
1952 | 68 | "resources": {
1953 | 69 | "subscribe": true // Only subscriptions supported
1954 | 70 | }
1955 | 71 | }
1956 | 72 | }
1957 | 73 | ```
1958 | 74 |
1959 | 75 | ```json
1960 | 76 | {
1961 | 77 | "capabilities": {
1962 | 78 | "resources": {
1963 | 79 | "listChanged": true // Only list change notifications supported
1964 | 80 | }
1965 | 81 | }
1966 | 82 | }
1967 | 83 | ```
1968 | 84 |
1969 | 85 | ## Protocol Messages
1970 | 86 |
1971 | 87 | ### Listing Resources
1972 | 88 |
1973 | 89 | To discover available resources, clients send a `resources/list` request. This operation
1974 | 90 | supports
1975 | 91 | [pagination]({{< ref "/specification/2024-11-05/server/utilities/pagination" >}}).
1976 | 92 |
1977 | 93 | **Request:**
1978 | 94 |
1979 | 95 | ```json
1980 | 96 | {
1981 | 97 | "jsonrpc": "2.0",
1982 | 98 | "id": 1,
1983 | 99 | "method": "resources/list",
1984 | 100 | "params": {
1985 | 101 | "cursor": "optional-cursor-value"
1986 | 102 | }
1987 | 103 | }
1988 | 104 | ```
1989 | 105 |
1990 | 106 | **Response:**
1991 | 107 |
1992 | 108 | ```json
1993 | 109 | {
1994 | 110 | "jsonrpc": "2.0",
1995 | 111 | "id": 1,
1996 | 112 | "result": {
1997 | 113 | "resources": [
1998 | 114 | {
1999 | 115 | "uri": "file:///project/src/main.rs",
2000 | 116 | "name": "main.rs",
2001 | 117 | "description": "Primary application entry point",
2002 | 118 | "mimeType": "text/x-rust"
2003 | 119 | }
2004 | 120 | ],
2005 | 121 | "nextCursor": "next-page-cursor"
2006 | 122 | }
2007 | 123 | }
2008 | 124 | ```
2009 | 125 |
2010 | 126 | ### Reading Resources
2011 | 127 |
2012 | 128 | To retrieve resource contents, clients send a `resources/read` request:
2013 | 129 |
2014 | 130 | **Request:**
2015 | 131 |
2016 | 132 | ```json
2017 | 133 | {
2018 | 134 | "jsonrpc": "2.0",
2019 | 135 | "id": 2,
2020 | 136 | "method": "resources/read",
2021 | 137 | "params": {
2022 | 138 | "uri": "file:///project/src/main.rs"
2023 | 139 | }
2024 | 140 | }
2025 | 141 | ```
2026 | 142 |
2027 | 143 | **Response:**
2028 | 144 |
2029 | 145 | ```json
2030 | 146 | {
2031 | 147 | "jsonrpc": "2.0",
2032 | 148 | "id": 2,
2033 | 149 | "result": {
2034 | 150 | "contents": [
2035 | 151 | {
2036 | 152 | "uri": "file:///project/src/main.rs",
2037 | 153 | "mimeType": "text/x-rust",
2038 | 154 | "text": "fn main() {\n println!(\"Hello world!\");\n}"
2039 | 155 | }
2040 | 156 | ]
2041 | 157 | }
2042 | 158 | }
2043 | 159 | ```
2044 | 160 |
2045 | 161 | ### Resource Templates
2046 | 162 |
2047 | 163 | Resource templates allow servers to expose parameterized resources using
2048 | 164 | [URI templates](https://datatracker.ietf.org/doc/html/rfc6570). Arguments may be
2049 | 165 | auto-completed through [the completion
2050 | 166 | API]({{< ref "/specification/2024-11-05/server/utilities/completion" >}}).
2051 | 167 |
2052 | 168 | **Request:**
2053 | 169 |
2054 | 170 | ```json
2055 | 171 | {
2056 | 172 | "jsonrpc": "2.0",
2057 | 173 | "id": 3,
2058 | 174 | "method": "resources/templates/list"
2059 | 175 | }
2060 | 176 | ```
2061 | 177 |
2062 | 178 | **Response:**
2063 | 179 |
2064 | 180 | ```json
2065 | 181 | {
2066 | 182 | "jsonrpc": "2.0",
2067 | 183 | "id": 3,
2068 | 184 | "result": {
2069 | 185 | "resourceTemplates": [
2070 | 186 | {
2071 | 187 | "uriTemplate": "file:///{path}",
2072 | 188 | "name": "Project Files",
2073 | 189 | "description": "Access files in the project directory",
2074 | 190 | "mimeType": "application/octet-stream"
2075 | 191 | }
2076 | 192 | ]
2077 | 193 | }
2078 | 194 | }
2079 | 195 | ```
2080 | 196 |
2081 | 197 | ### List Changed Notification
2082 | 198 |
2083 | 199 | When the list of available resources changes, servers that declared the `listChanged`
2084 | 200 | capability **SHOULD** send a notification:
2085 | 201 |
2086 | 202 | ```json
2087 | 203 | {
2088 | 204 | "jsonrpc": "2.0",
2089 | 205 | "method": "notifications/resources/list_changed"
2090 | 206 | }
2091 | 207 | ```
2092 | 208 |
2093 | 209 | ### Subscriptions
2094 | 210 |
2095 | 211 | The protocol supports optional subscriptions to resource changes. Clients can subscribe
2096 | 212 | to specific resources and receive notifications when they change:
2097 | 213 |
2098 | 214 | **Subscribe Request:**
2099 | 215 |
2100 | 216 | ```json
2101 | 217 | {
2102 | 218 | "jsonrpc": "2.0",
2103 | 219 | "id": 4,
2104 | 220 | "method": "resources/subscribe",
2105 | 221 | "params": {
2106 | 222 | "uri": "file:///project/src/main.rs"
2107 | 223 | }
2108 | 224 | }
2109 | 225 | ```
2110 | 226 |
2111 | 227 | **Update Notification:**
2112 | 228 |
2113 | 229 | ```json
2114 | 230 | {
2115 | 231 | "jsonrpc": "2.0",
2116 | 232 | "method": "notifications/resources/updated",
2117 | 233 | "params": {
2118 | 234 | "uri": "file:///project/src/main.rs"
2119 | 235 | }
2120 | 236 | }
2121 | 237 | ```
2122 | 238 |
2123 | 239 | ## Message Flow
2124 | 240 |
2125 | 241 | ```mermaid
2126 | 242 | sequenceDiagram
2127 | 243 | participant Client
2128 | 244 | participant Server
2129 | 245 |
2130 | 246 | Note over Client,Server: Resource Discovery
2131 | 247 | Client->>Server: resources/list
2132 | 248 | Server-->>Client: List of resources
2133 | 249 |
2134 | 250 | Note over Client,Server: Resource Access
2135 | 251 | Client->>Server: resources/read
2136 | 252 | Server-->>Client: Resource contents
2137 | 253 |
2138 | 254 | Note over Client,Server: Subscriptions
2139 | 255 | Client->>Server: resources/subscribe
2140 | 256 | Server-->>Client: Subscription confirmed
2141 | 257 |
2142 | 258 | Note over Client,Server: Updates
2143 | 259 | Server--)Client: notifications/resources/updated
2144 | 260 | Client->>Server: resources/read
2145 | 261 | Server-->>Client: Updated contents
2146 | 262 | ```
2147 | 263 |
2148 | 264 | ## Data Types
2149 | 265 |
2150 | 266 | ### Resource
2151 | 267 |
2152 | 268 | A resource definition includes:
2153 | 269 |
2154 | 270 | - `uri`: Unique identifier for the resource
2155 | 271 | - `name`: Human-readable name
2156 | 272 | - `description`: Optional description
2157 | 273 | - `mimeType`: Optional MIME type
2158 | 274 |
2159 | 275 | ### Resource Contents
2160 | 276 |
2161 | 277 | Resources can contain either text or binary data:
2162 | 278 |
2163 | 279 | #### Text Content
2164 | 280 |
2165 | 281 | ```json
2166 | 282 | {
2167 | 283 | "uri": "file:///example.txt",
2168 | 284 | "mimeType": "text/plain",
2169 | 285 | "text": "Resource content"
2170 | 286 | }
2171 | 287 | ```
2172 | 288 |
2173 | 289 | #### Binary Content
2174 | 290 |
2175 | 291 | ```json
2176 | 292 | {
2177 | 293 | "uri": "file:///example.png",
2178 | 294 | "mimeType": "image/png",
2179 | 295 | "blob": "base64-encoded-data"
2180 | 296 | }
2181 | 297 | ```
2182 | 298 |
2183 | 299 | ## Common URI Schemes
2184 | 300 |
2185 | 301 | The protocol defines several standard URI schemes. This list not
2186 | 302 | exhaustive—implementations are always free to use additional, custom URI schemes.
2187 | 303 |
2188 | 304 | ### https://
2189 | 305 |
2190 | 306 | Used to represent a resource available on the web.
2191 | 307 |
2192 | 308 | Servers **SHOULD** use this scheme only when the client is able to fetch and load the
2193 | 309 | resource directly from the web on its own—that is, it doesn’t need to read the resource
2194 | 310 | via the MCP server.
2195 | 311 |
2196 | 312 | For other use cases, servers **SHOULD** prefer to use another URI scheme, or define a
2197 | 313 | custom one, even if the server will itself be downloading resource contents over the
2198 | 314 | internet.
2199 | 315 |
2200 | 316 | ### file://
2201 | 317 |
2202 | 318 | Used to identify resources that behave like a filesystem. However, the resources do not
2203 | 319 | need to map to an actual physical filesystem.
2204 | 320 |
2205 | 321 | MCP servers **MAY** identify file:// resources with an
2206 | 322 | [XDG MIME type](https://specifications.freedesktop.org/shared-mime-info-spec/0.14/ar01s02.html#id-1.3.14),
2207 | 323 | like `inode/directory`, to represent non-regular files (such as directories) that don’t
2208 | 324 | otherwise have a standard MIME type.
2209 | 325 |
2210 | 326 | ### git://
2211 | 327 |
2212 | 328 | Git version control integration.
2213 | 329 |
2214 | 330 | ## Error Handling
2215 | 331 |
2216 | 332 | Servers **SHOULD** return standard JSON-RPC errors for common failure cases:
2217 | 333 |
2218 | 334 | - Resource not found: `-32002`
2219 | 335 | - Internal errors: `-32603`
2220 | 336 |
2221 | 337 | Example error:
2222 | 338 |
2223 | 339 | ```json
2224 | 340 | {
2225 | 341 | "jsonrpc": "2.0",
2226 | 342 | "id": 5,
2227 | 343 | "error": {
2228 | 344 | "code": -32002,
2229 | 345 | "message": "Resource not found",
2230 | 346 | "data": {
2231 | 347 | "uri": "file:///nonexistent.txt"
2232 | 348 | }
2233 | 349 | }
2234 | 350 | }
2235 | 351 | ```
2236 | 352 |
2237 | 353 | ## Security Considerations
2238 | 354 |
2239 | 355 | 1. Servers **MUST** validate all resource URIs
2240 | 356 | 2. Access controls **SHOULD** be implemented for sensitive resources
2241 | 357 | 3. Binary data **MUST** be properly encoded
2242 | 358 | 4. Resource permissions **SHOULD** be checked before operations
2243 | 359 |
2244 |
2245 |
2246 | --------------------------------------------------------------------------------
2247 | /docs/specification/2024-11-05/server/slash-command.png:
2248 | --------------------------------------------------------------------------------
2249 | https://raw.githubusercontent.com/modelcontextprotocol/specification/main/docs/specification/2024-11-05/server/slash-command.png
2250 |
2251 |
2252 | --------------------------------------------------------------------------------
2253 | /docs/specification/2024-11-05/server/tools.md:
2254 | --------------------------------------------------------------------------------
2255 | 1 | ---
2256 | 2 | title: Tools
2257 | 3 | type: docs
2258 | 4 | weight: 40
2259 | 5 | ---
2260 | 6 |
2261 | 7 | {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
2262 | 8 |
2263 | 9 | The Model Context Protocol (MCP) allows servers to expose tools that can be invoked by
2264 | 10 | language models. Tools enable models to interact with external systems, such as querying
2265 | 11 | databases, calling APIs, or performing computations. Each tool is uniquely identified by
2266 | 12 | a name and includes metadata describing its schema.
2267 | 13 |
2268 | 14 | ## User Interaction Model
2269 | 15 |
2270 | 16 | Tools in MCP are designed to be **model-controlled**, meaning that the language model can
2271 | 17 | discover and invoke tools automatically based on its contextual understanding and the
2272 | 18 | user's prompts.
2273 | 19 |
2274 | 20 | However, implementations are free to expose tools through any interface pattern that
2275 | 21 | suits their needs—the protocol itself does not mandate any specific user
2276 | 22 | interaction model.
2277 | 23 |
2278 | 24 | {{< callout type="warning" >}} For trust & safety and security, there **SHOULD** always
2279 | 25 | be a human in the loop with the ability to deny tool invocations.
2280 | 26 |
2281 | 27 | Applications **SHOULD**:
2282 | 28 |
2283 | 29 | - Provide UI that makes clear which tools are being exposed to the AI model
2284 | 30 | - Insert clear visual indicators when tools are invoked
2285 | 31 | - Present confirmation prompts to the user for operations, to ensure a human is in the
2286 | 32 | loop {{< /callout >}}
2287 | 33 |
2288 | 34 | ## Capabilities
2289 | 35 |
2290 | 36 | Servers that support tools **MUST** declare the `tools` capability:
2291 | 37 |
2292 | 38 | ```json
2293 | 39 | {
2294 | 40 | "capabilities": {
2295 | 41 | "tools": {
2296 | 42 | "listChanged": true
2297 | 43 | }
2298 | 44 | }
2299 | 45 | }
2300 | 46 | ```
2301 | 47 |
2302 | 48 | `listChanged` indicates whether the server will emit notifications when the list of
2303 | 49 | available tools changes.
2304 | 50 |
2305 | 51 | ## Protocol Messages
2306 | 52 |
2307 | 53 | ### Listing Tools
2308 | 54 |
2309 | 55 | To discover available tools, clients send a `tools/list` request. This operation supports
2310 | 56 | [pagination]({{< ref "/specification/2024-11-05/server/utilities/pagination" >}}).
2311 | 57 |
2312 | 58 | **Request:**
2313 | 59 |
2314 | 60 | ```json
2315 | 61 | {
2316 | 62 | "jsonrpc": "2.0",
2317 | 63 | "id": 1,
2318 | 64 | "method": "tools/list",
2319 | 65 | "params": {
2320 | 66 | "cursor": "optional-cursor-value"
2321 | 67 | }
2322 | 68 | }
2323 | 69 | ```
2324 | 70 |
2325 | 71 | **Response:**
2326 | 72 |
2327 | 73 | ```json
2328 | 74 | {
2329 | 75 | "jsonrpc": "2.0",
2330 | 76 | "id": 1,
2331 | 77 | "result": {
2332 | 78 | "tools": [
2333 | 79 | {
2334 | 80 | "name": "get_weather",
2335 | 81 | "description": "Get current weather information for a location",
2336 | 82 | "inputSchema": {
2337 | 83 | "type": "object",
2338 | 84 | "properties": {
2339 | 85 | "location": {
2340 | 86 | "type": "string",
2341 | 87 | "description": "City name or zip code"
2342 | 88 | }
2343 | 89 | },
2344 | 90 | "required": ["location"]
2345 | 91 | }
2346 | 92 | }
2347 | 93 | ],
2348 | 94 | "nextCursor": "next-page-cursor"
2349 | 95 | }
2350 | 96 | }
2351 | 97 | ```
2352 | 98 |
2353 | 99 | ### Calling Tools
2354 | 100 |
2355 | 101 | To invoke a tool, clients send a `tools/call` request:
2356 | 102 |
2357 | 103 | **Request:**
2358 | 104 |
2359 | 105 | ```json
2360 | 106 | {
2361 | 107 | "jsonrpc": "2.0",
2362 | 108 | "id": 2,
2363 | 109 | "method": "tools/call",
2364 | 110 | "params": {
2365 | 111 | "name": "get_weather",
2366 | 112 | "arguments": {
2367 | 113 | "location": "New York"
2368 | 114 | }
2369 | 115 | }
2370 | 116 | }
2371 | 117 | ```
2372 | 118 |
2373 | 119 | **Response:**
2374 | 120 |
2375 | 121 | ```json
2376 | 122 | {
2377 | 123 | "jsonrpc": "2.0",
2378 | 124 | "id": 2,
2379 | 125 | "result": {
2380 | 126 | "content": [
2381 | 127 | {
2382 | 128 | "type": "text",
2383 | 129 | "text": "Current weather in New York:\nTemperature: 72°F\nConditions: Partly cloudy"
2384 | 130 | }
2385 | 131 | ],
2386 | 132 | "isError": false
2387 | 133 | }
2388 | 134 | }
2389 | 135 | ```
2390 | 136 |
2391 | 137 | ### List Changed Notification
2392 | 138 |
2393 | 139 | When the list of available tools changes, servers that declared the `listChanged`
2394 | 140 | capability **SHOULD** send a notification:
2395 | 141 |
2396 | 142 | ```json
2397 | 143 | {
2398 | 144 | "jsonrpc": "2.0",
2399 | 145 | "method": "notifications/tools/list_changed"
2400 | 146 | }
2401 | 147 | ```
2402 | 148 |
2403 | 149 | ## Message Flow
2404 | 150 |
2405 | 151 | ```mermaid
2406 | 152 | sequenceDiagram
2407 | 153 | participant LLM
2408 | 154 | participant Client
2409 | 155 | participant Server
2410 | 156 |
2411 | 157 | Note over Client,Server: Discovery
2412 | 158 | Client->>Server: tools/list
2413 | 159 | Server-->>Client: List of tools
2414 | 160 |
2415 | 161 | Note over Client,LLM: Tool Selection
2416 | 162 | LLM->>Client: Select tool to use
2417 | 163 |
2418 | 164 | Note over Client,Server: Invocation
2419 | 165 | Client->>Server: tools/call
2420 | 166 | Server-->>Client: Tool result
2421 | 167 | Client->>LLM: Process result
2422 | 168 |
2423 | 169 | Note over Client,Server: Updates
2424 | 170 | Server--)Client: tools/list_changed
2425 | 171 | Client->>Server: tools/list
2426 | 172 | Server-->>Client: Updated tools
2427 | 173 | ```
2428 | 174 |
2429 | 175 | ## Data Types
2430 | 176 |
2431 | 177 | ### Tool
2432 | 178 |
2433 | 179 | A tool definition includes:
2434 | 180 |
2435 | 181 | - `name`: Unique identifier for the tool
2436 | 182 | - `description`: Human-readable description of functionality
2437 | 183 | - `inputSchema`: JSON Schema defining expected parameters
2438 | 184 |
2439 | 185 | ### Tool Result
2440 | 186 |
2441 | 187 | Tool results can contain multiple content items of different types:
2442 | 188 |
2443 | 189 | #### Text Content
2444 | 190 |
2445 | 191 | ```json
2446 | 192 | {
2447 | 193 | "type": "text",
2448 | 194 | "text": "Tool result text"
2449 | 195 | }
2450 | 196 | ```
2451 | 197 |
2452 | 198 | #### Image Content
2453 | 199 |
2454 | 200 | ```json
2455 | 201 | {
2456 | 202 | "type": "image",
2457 | 203 | "data": "base64-encoded-data",
2458 | 204 | "mimeType": "image/png"
2459 | 205 | }
2460 | 206 | ```
2461 | 207 |
2462 | 208 | #### Embedded Resources
2463 | 209 |
2464 | 210 | [Resources]({{< ref "/specification/2024-11-05/server/resources" >}}) **MAY** be
2465 | 211 | embedded, to provide additional context or data, behind a URI that can be subscribed to
2466 | 212 | or fetched again by the client later:
2467 | 213 |
2468 | 214 | ```json
2469 | 215 | {
2470 | 216 | "type": "resource",
2471 | 217 | "resource": {
2472 | 218 | "uri": "resource://example",
2473 | 219 | "mimeType": "text/plain",
2474 | 220 | "text": "Resource content"
2475 | 221 | }
2476 | 222 | }
2477 | 223 | ```
2478 | 224 |
2479 | 225 | ## Error Handling
2480 | 226 |
2481 | 227 | Tools use two error reporting mechanisms:
2482 | 228 |
2483 | 229 | 1. **Protocol Errors**: Standard JSON-RPC errors for issues like:
2484 | 230 |
2485 | 231 | - Unknown tools
2486 | 232 | - Invalid arguments
2487 | 233 | - Server errors
2488 | 234 |
2489 | 235 | 2. **Tool Execution Errors**: Reported in tool results with `isError: true`:
2490 | 236 | - API failures
2491 | 237 | - Invalid input data
2492 | 238 | - Business logic errors
2493 | 239 |
2494 | 240 | Example protocol error:
2495 | 241 |
2496 | 242 | ```json
2497 | 243 | {
2498 | 244 | "jsonrpc": "2.0",
2499 | 245 | "id": 3,
2500 | 246 | "error": {
2501 | 247 | "code": -32602,
2502 | 248 | "message": "Unknown tool: invalid_tool_name"
2503 | 249 | }
2504 | 250 | }
2505 | 251 | ```
2506 | 252 |
2507 | 253 | Example tool execution error:
2508 | 254 |
2509 | 255 | ```json
2510 | 256 | {
2511 | 257 | "jsonrpc": "2.0",
2512 | 258 | "id": 4,
2513 | 259 | "result": {
2514 | 260 | "content": [
2515 | 261 | {
2516 | 262 | "type": "text",
2517 | 263 | "text": "Failed to fetch weather data: API rate limit exceeded"
2518 | 264 | }
2519 | 265 | ],
2520 | 266 | "isError": true
2521 | 267 | }
2522 | 268 | }
2523 | 269 | ```
2524 | 270 |
2525 | 271 | ## Security Considerations
2526 | 272 |
2527 | 273 | 1. Servers **MUST**:
2528 | 274 |
2529 | 275 | - Validate all tool inputs
2530 | 276 | - Implement proper access controls
2531 | 277 | - Rate limit tool invocations
2532 | 278 | - Sanitize tool outputs
2533 | 279 |
2534 | 280 | 2. Clients **SHOULD**:
2535 | 281 | - Prompt for user confirmation on sensitive operations
2536 | 282 | - Show tool inputs to the user before calling the server, to avoid malicious or
2537 | 283 | accidental data exfiltration
2538 | 284 | - Validate tool results before passing to LLM
2539 | 285 | - Implement timeouts for tool calls
2540 | 286 | - Log tool usage for audit purposes
2541 | 287 |
2542 |
2543 |
2544 | --------------------------------------------------------------------------------
2545 | /docs/specification/2024-11-05/server/utilities/_index.md:
2546 | --------------------------------------------------------------------------------
2547 | 1 | ---
2548 | 2 | title: Utilities
2549 | 3 | ---
2550 | 4 |
2551 | 5 | {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
2552 | 6 |
2553 | 7 | These optional features can be used to enhance server functionality.
2554 | 8 |
2555 | 9 | {{< cards >}} {{< card link="completion" title="Completion" icon="at-symbol" >}}
2556 | 10 | {{< card link="logging" title="Logging" icon="terminal" >}}
2557 | 11 | {{< card link="pagination" title="Pagination" icon="collection" >}} {{< /cards >}}
2558 | 12 |
2559 |
2560 |
2561 | --------------------------------------------------------------------------------
2562 | /docs/specification/2024-11-05/server/utilities/completion.md:
2563 | --------------------------------------------------------------------------------
2564 | 1 | ---
2565 | 2 | title: Completion
2566 | 3 | ---
2567 | 4 |
2568 | 5 | {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
2569 | 6 |
2570 | 7 | The Model Context Protocol (MCP) provides a standardized way for servers to offer
2571 | 8 | argument autocompletion suggestions for prompts and resource URIs. This enables rich,
2572 | 9 | IDE-like experiences where users receive contextual suggestions while entering argument
2573 | 10 | values.
2574 | 11 |
2575 | 12 | ## User Interaction Model
2576 | 13 |
2577 | 14 | Completion in MCP is designed to support interactive user experiences similar to IDE code
2578 | 15 | completion.
2579 | 16 |
2580 | 17 | For example, applications may show completion suggestions in a dropdown or popup menu as
2581 | 18 | users type, with the ability to filter and select from available options.
2582 | 19 |
2583 | 20 | However, implementations are free to expose completion through any interface pattern that
2584 | 21 | suits their needs—the protocol itself does not mandate any specific user
2585 | 22 | interaction model.
2586 | 23 |
2587 | 24 | ## Protocol Messages
2588 | 25 |
2589 | 26 | ### Requesting Completions
2590 | 27 |
2591 | 28 | To get completion suggestions, clients send a `completion/complete` request specifying
2592 | 29 | what is being completed through a reference type:
2593 | 30 |
2594 | 31 | **Request:**
2595 | 32 |
2596 | 33 | ```json
2597 | 34 | {
2598 | 35 | "jsonrpc": "2.0",
2599 | 36 | "id": 1,
2600 | 37 | "method": "completion/complete",
2601 | 38 | "params": {
2602 | 39 | "ref": {
2603 | 40 | "type": "ref/prompt",
2604 | 41 | "name": "code_review"
2605 | 42 | },
2606 | 43 | "argument": {
2607 | 44 | "name": "language",
2608 | 45 | "value": "py"
2609 | 46 | }
2610 | 47 | }
2611 | 48 | }
2612 | 49 | ```
2613 | 50 |
2614 | 51 | **Response:**
2615 | 52 |
2616 | 53 | ```json
2617 | 54 | {
2618 | 55 | "jsonrpc": "2.0",
2619 | 56 | "id": 1,
2620 | 57 | "result": {
2621 | 58 | "completion": {
2622 | 59 | "values": ["python", "pytorch", "pyside"],
2623 | 60 | "total": 10,
2624 | 61 | "hasMore": true
2625 | 62 | }
2626 | 63 | }
2627 | 64 | }
2628 | 65 | ```
2629 | 66 |
2630 | 67 | ### Reference Types
2631 | 68 |
2632 | 69 | The protocol supports two types of completion references:
2633 | 70 |
2634 | 71 | | Type | Description | Example |
2635 | 72 | | -------------- | --------------------------- | --------------------------------------------------- |
2636 | 73 | | `ref/prompt` | References a prompt by name | `{"type": "ref/prompt", "name": "code_review"}` |
2637 | 74 | | `ref/resource` | References a resource URI | `{"type": "ref/resource", "uri": "file:///{path}"}` |
2638 | 75 |
2639 | 76 | ### Completion Results
2640 | 77 |
2641 | 78 | Servers return an array of completion values ranked by relevance, with:
2642 | 79 |
2643 | 80 | - Maximum 100 items per response
2644 | 81 | - Optional total number of available matches
2645 | 82 | - Boolean indicating if additional results exist
2646 | 83 |
2647 | 84 | ## Message Flow
2648 | 85 |
2649 | 86 | ```mermaid
2650 | 87 | sequenceDiagram
2651 | 88 | participant Client
2652 | 89 | participant Server
2653 | 90 |
2654 | 91 | Note over Client: User types argument
2655 | 92 | Client->>Server: completion/complete
2656 | 93 | Server-->>Client: Completion suggestions
2657 | 94 |
2658 | 95 | Note over Client: User continues typing
2659 | 96 | Client->>Server: completion/complete
2660 | 97 | Server-->>Client: Refined suggestions
2661 | 98 | ```
2662 | 99 |
2663 | 100 | ## Data Types
2664 | 101 |
2665 | 102 | ### CompleteRequest
2666 | 103 |
2667 | 104 | - `ref`: A `PromptReference` or `ResourceReference`
2668 | 105 | - `argument`: Object containing:
2669 | 106 | - `name`: Argument name
2670 | 107 | - `value`: Current value
2671 | 108 |
2672 | 109 | ### CompleteResult
2673 | 110 |
2674 | 111 | - `completion`: Object containing:
2675 | 112 | - `values`: Array of suggestions (max 100)
2676 | 113 | - `total`: Optional total matches
2677 | 114 | - `hasMore`: Additional results flag
2678 | 115 |
2679 | 116 | ## Implementation Considerations
2680 | 117 |
2681 | 118 | 1. Servers **SHOULD**:
2682 | 119 |
2683 | 120 | - Return suggestions sorted by relevance
2684 | 121 | - Implement fuzzy matching where appropriate
2685 | 122 | - Rate limit completion requests
2686 | 123 | - Validate all inputs
2687 | 124 |
2688 | 125 | 2. Clients **SHOULD**:
2689 | 126 | - Debounce rapid completion requests
2690 | 127 | - Cache completion results where appropriate
2691 | 128 | - Handle missing or partial results gracefully
2692 | 129 |
2693 | 130 | ## Security
2694 | 131 |
2695 | 132 | Implementations **MUST**:
2696 | 133 |
2697 | 134 | - Validate all completion inputs
2698 | 135 | - Implement appropriate rate limiting
2699 | 136 | - Control access to sensitive suggestions
2700 | 137 | - Prevent completion-based information disclosure
2701 | 138 |
2702 |
2703 |
2704 | --------------------------------------------------------------------------------
2705 | /docs/specification/2024-11-05/server/utilities/logging.md:
2706 | --------------------------------------------------------------------------------
2707 | 1 | ---
2708 | 2 | title: Logging
2709 | 3 | ---
2710 | 4 |
2711 | 5 | {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
2712 | 6 |
2713 | 7 | The Model Context Protocol (MCP) provides a standardized way for servers to send
2714 | 8 | structured log messages to clients. Clients can control logging verbosity by setting
2715 | 9 | minimum log levels, with servers sending notifications containing severity levels,
2716 | 10 | optional logger names, and arbitrary JSON-serializable data.
2717 | 11 |
2718 | 12 | ## User Interaction Model
2719 | 13 |
2720 | 14 | Implementations are free to expose logging through any interface pattern that suits their
2721 | 15 | needs—the protocol itself does not mandate any specific user interaction model.
2722 | 16 |
2723 | 17 | ## Capabilities
2724 | 18 |
2725 | 19 | Servers that emit log message notifications **MUST** declare the `logging` capability:
2726 | 20 |
2727 | 21 | ```json
2728 | 22 | {
2729 | 23 | "capabilities": {
2730 | 24 | "logging": {}
2731 | 25 | }
2732 | 26 | }
2733 | 27 | ```
2734 | 28 |
2735 | 29 | ## Log Levels
2736 | 30 |
2737 | 31 | The protocol follows the standard syslog severity levels specified in
2738 | 32 | [RFC 5424](https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1):
2739 | 33 |
2740 | 34 | | Level | Description | Example Use Case |
2741 | 35 | | --------- | -------------------------------- | -------------------------- |
2742 | 36 | | debug | Detailed debugging information | Function entry/exit points |
2743 | 37 | | info | General informational messages | Operation progress updates |
2744 | 38 | | notice | Normal but significant events | Configuration changes |
2745 | 39 | | warning | Warning conditions | Deprecated feature usage |
2746 | 40 | | error | Error conditions | Operation failures |
2747 | 41 | | critical | Critical conditions | System component failures |
2748 | 42 | | alert | Action must be taken immediately | Data corruption detected |
2749 | 43 | | emergency | System is unusable | Complete system failure |
2750 | 44 |
2751 | 45 | ## Protocol Messages
2752 | 46 |
2753 | 47 | ### Setting Log Level
2754 | 48 |
2755 | 49 | To configure the minimum log level, clients **MAY** send a `logging/setLevel` request:
2756 | 50 |
2757 | 51 | **Request:**
2758 | 52 |
2759 | 53 | ```json
2760 | 54 | {
2761 | 55 | "jsonrpc": "2.0",
2762 | 56 | "id": 1,
2763 | 57 | "method": "logging/setLevel",
2764 | 58 | "params": {
2765 | 59 | "level": "info"
2766 | 60 | }
2767 | 61 | }
2768 | 62 | ```
2769 | 63 |
2770 | 64 | ### Log Message Notifications
2771 | 65 |
2772 | 66 | Servers send log messages using `notifications/message` notifications:
2773 | 67 |
2774 | 68 | ```json
2775 | 69 | {
2776 | 70 | "jsonrpc": "2.0",
2777 | 71 | "method": "notifications/message",
2778 | 72 | "params": {
2779 | 73 | "level": "error",
2780 | 74 | "logger": "database",
2781 | 75 | "data": {
2782 | 76 | "error": "Connection failed",
2783 | 77 | "details": {
2784 | 78 | "host": "localhost",
2785 | 79 | "port": 5432
2786 | 80 | }
2787 | 81 | }
2788 | 82 | }
2789 | 83 | }
2790 | 84 | ```
2791 | 85 |
2792 | 86 | ## Message Flow
2793 | 87 |
2794 | 88 | ```mermaid
2795 | 89 | sequenceDiagram
2796 | 90 | participant Client
2797 | 91 | participant Server
2798 | 92 |
2799 | 93 | Note over Client,Server: Configure Logging
2800 | 94 | Client->>Server: logging/setLevel (info)
2801 | 95 | Server-->>Client: Empty Result
2802 | 96 |
2803 | 97 | Note over Client,Server: Server Activity
2804 | 98 | Server--)Client: notifications/message (info)
2805 | 99 | Server--)Client: notifications/message (warning)
2806 | 100 | Server--)Client: notifications/message (error)
2807 | 101 |
2808 | 102 | Note over Client,Server: Level Change
2809 | 103 | Client->>Server: logging/setLevel (error)
2810 | 104 | Server-->>Client: Empty Result
2811 | 105 | Note over Server: Only sends error level<br/>and above
2812 | 106 | ```
2813 | 107 |
2814 | 108 | ## Error Handling
2815 | 109 |
2816 | 110 | Servers **SHOULD** return standard JSON-RPC errors for common failure cases:
2817 | 111 |
2818 | 112 | - Invalid log level: `-32602` (Invalid params)
2819 | 113 | - Configuration errors: `-32603` (Internal error)
2820 | 114 |
2821 | 115 | ## Implementation Considerations
2822 | 116 |
2823 | 117 | 1. Servers **SHOULD**:
2824 | 118 |
2825 | 119 | - Rate limit log messages
2826 | 120 | - Include relevant context in data field
2827 | 121 | - Use consistent logger names
2828 | 122 | - Remove sensitive information
2829 | 123 |
2830 | 124 | 2. Clients **MAY**:
2831 | 125 | - Present log messages in the UI
2832 | 126 | - Implement log filtering/search
2833 | 127 | - Display severity visually
2834 | 128 | - Persist log messages
2835 | 129 |
2836 | 130 | ## Security
2837 | 131 |
2838 | 132 | 1. Log messages **MUST NOT** contain:
2839 | 133 |
2840 | 134 | - Credentials or secrets
2841 | 135 | - Personal identifying information
2842 | 136 | - Internal system details that could aid attacks
2843 | 137 |
2844 | 138 | 2. Implementations **SHOULD**:
2845 | 139 | - Rate limit messages
2846 | 140 | - Validate all data fields
2847 | 141 | - Control log access
2848 | 142 | - Monitor for sensitive content
2849 | 143 |
2850 |
2851 |
2852 | --------------------------------------------------------------------------------
2853 | /docs/specification/2024-11-05/server/utilities/pagination.md:
2854 | --------------------------------------------------------------------------------
2855 | 1 | ---
2856 | 2 | title: Pagination
2857 | 3 | ---
2858 | 4 |
2859 | 5 | {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
2860 | 6 |
2861 | 7 | The Model Context Protocol (MCP) supports paginating list operations that may return
2862 | 8 | large result sets. Pagination allows servers to yield results in smaller chunks rather
2863 | 9 | than all at once.
2864 | 10 |
2865 | 11 | Pagination is especially important when connecting to external services over the
2866 | 12 | internet, but also useful for local integrations to avoid performance issues with large
2867 | 13 | data sets.
2868 | 14 |
2869 | 15 | ## Pagination Model
2870 | 16 |
2871 | 17 | Pagination in MCP uses an opaque cursor-based approach, instead of numbered pages.
2872 | 18 |
2873 | 19 | - The **cursor** is an opaque string token, representing a position in the result set
2874 | 20 | - **Page size** is determined by the server, and **MAY NOT** be fixed
2875 | 21 |
2876 | 22 | ## Response Format
2877 | 23 |
2878 | 24 | Pagination starts when the server sends a **response** that includes:
2879 | 25 |
2880 | 26 | - The current page of results
2881 | 27 | - An optional `nextCursor` field if more results exist
2882 | 28 |
2883 | 29 | ```json
2884 | 30 | {
2885 | 31 | "jsonrpc": "2.0",
2886 | 32 | "id": "123",
2887 | 33 | "result": {
2888 | 34 | "resources": [...],
2889 | 35 | "nextCursor": "eyJwYWdlIjogM30="
2890 | 36 | }
2891 | 37 | }
2892 | 38 | ```
2893 | 39 |
2894 | 40 | ## Request Format
2895 | 41 |
2896 | 42 | After receiving a cursor, the client can _continue_ paginating by issuing a request
2897 | 43 | including that cursor:
2898 | 44 |
2899 | 45 | ```json
2900 | 46 | {
2901 | 47 | "jsonrpc": "2.0",
2902 | 48 | "method": "resources/list",
2903 | 49 | "params": {
2904 | 50 | "cursor": "eyJwYWdlIjogMn0="
2905 | 51 | }
2906 | 52 | }
2907 | 53 | ```
2908 | 54 |
2909 | 55 | ## Pagination Flow
2910 | 56 |
2911 | 57 | ```mermaid
2912 | 58 | sequenceDiagram
2913 | 59 | participant Client
2914 | 60 | participant Server
2915 | 61 |
2916 | 62 | Client->>Server: List Request (no cursor)
2917 | 63 | loop Pagination Loop
2918 | 64 | Server-->>Client: Page of results + nextCursor
2919 | 65 | Client->>Server: List Request (with cursor)
2920 | 66 | end
2921 | 67 | ```
2922 | 68 |
2923 | 69 | ## Operations Supporting Pagination
2924 | 70 |
2925 | 71 | The following MCP operations support pagination:
2926 | 72 |
2927 | 73 | - `resources/list` - List available resources
2928 | 74 | - `resources/templates/list` - List resource templates
2929 | 75 | - `prompts/list` - List available prompts
2930 | 76 | - `tools/list` - List available tools
2931 | 77 |
2932 | 78 | ## Implementation Guidelines
2933 | 79 |
2934 | 80 | 1. Servers **SHOULD**:
2935 | 81 |
2936 | 82 | - Provide stable cursors
2937 | 83 | - Handle invalid cursors gracefully
2938 | 84 |
2939 | 85 | 2. Clients **SHOULD**:
2940 | 86 |
2941 | 87 | - Treat a missing `nextCursor` as the end of results
2942 | 88 | - Support both paginated and non-paginated flows
2943 | 89 |
2944 | 90 | 3. Clients **MUST** treat cursors as opaque tokens:
2945 | 91 | - Don't make assumptions about cursor format
2946 | 92 | - Don't attempt to parse or modify cursors
2947 | 93 | - Don't persist cursors across sessions
2948 | 94 |
2949 | 95 | ## Error Handling
2950 | 96 |
2951 | 97 | Invalid cursors **SHOULD** result in an error with code -32602 (Invalid params).
2952 | 98 |
2953 |
2954 |
2955 | --------------------------------------------------------------------------------
2956 |
```