This is page 3 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/2025-03-26.txt:
--------------------------------------------------------------------------------
```
1 | └── docs
2 | └── specification
3 | └── 2025-03-26
4 | ├── _index.md
5 | ├── architecture
6 | └── _index.md
7 | ├── basic
8 | ├── _index.md
9 | ├── authorization.md
10 | ├── lifecycle.md
11 | ├── transports.md
12 | └── utilities
13 | │ ├── _index.md
14 | │ ├── cancellation.md
15 | │ ├── ping.md
16 | │ └── progress.md
17 | ├── changelog.md
18 | ├── client
19 | ├── _index.md
20 | ├── roots.md
21 | └── sampling.md
22 | └── server
23 | ├── _index.md
24 | ├── prompts.md
25 | ├── resource-picker.png
26 | ├── resources.md
27 | ├── slash-command.png
28 | ├── tools.md
29 | └── utilities
30 | ├── _index.md
31 | ├── completion.md
32 | ├── logging.md
33 | └── pagination.md
34 |
35 |
36 | /docs/specification/2025-03-26/_index.md:
37 | --------------------------------------------------------------------------------
38 | 1 | ---
39 | 2 | linkTitle: 2025-03-26 (Latest)
40 | 3 | title: Model Context Protocol specification
41 | 4 | cascade:
42 | 5 | type: docs
43 | 6 | breadcrumbs: false
44 | 7 | weight: 1
45 | 8 | aliases:
46 | 9 | - /latest
47 | 10 | ---
48 | 11 |
49 | 12 | {{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}}
50 | 13 |
51 | 14 | [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open protocol that
52 | 15 | enables seamless integration between LLM applications and external data sources and
53 | 16 | tools. Whether you're building an AI-powered IDE, enhancing a chat interface, or creating
54 | 17 | custom AI workflows, MCP provides a standardized way to connect LLMs with the context
55 | 18 | they need.
56 | 19 |
57 | 20 | This specification defines the authoritative protocol requirements, based on the
58 | 21 | TypeScript schema in
59 | 22 | [schema.ts](https://github.com/modelcontextprotocol/specification/blob/main/schema/draft/schema.ts).
60 | 23 |
61 | 24 | For implementation guides and examples, visit
62 | 25 | [modelcontextprotocol.io](https://modelcontextprotocol.io).
63 | 26 |
64 | 27 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD
65 | 28 | NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
66 | 29 | interpreted as described in [BCP 14](https://datatracker.ietf.org/doc/html/bcp14)
67 | 30 | [[RFC2119](https://datatracker.ietf.org/doc/html/rfc2119)]
68 | 31 | [[RFC8174](https://datatracker.ietf.org/doc/html/rfc8174)] when, and only when, they
69 | 32 | appear in all capitals, as shown here.
70 | 33 |
71 | 34 | ## Overview
72 | 35 |
73 | 36 | MCP provides a standardized way for applications to:
74 | 37 |
75 | 38 | - Share contextual information with language models
76 | 39 | - Expose tools and capabilities to AI systems
77 | 40 | - Build composable integrations and workflows
78 | 41 |
79 | 42 | The protocol uses [JSON-RPC](https://www.jsonrpc.org/) 2.0 messages to establish
80 | 43 | communication between:
81 | 44 |
82 | 45 | - **Hosts**: LLM applications that initiate connections
83 | 46 | - **Clients**: Connectors within the host application
84 | 47 | - **Servers**: Services that provide context and capabilities
85 | 48 |
86 | 49 | MCP takes some inspiration from the
87 | 50 | [Language Server Protocol](https://microsoft.github.io/language-server-protocol/), which
88 | 51 | standardizes how to add support for programming languages across a whole ecosystem of
89 | 52 | development tools. In a similar way, MCP standardizes how to integrate additional context
90 | 53 | and tools into the ecosystem of AI applications.
91 | 54 |
92 | 55 | ## Key Details
93 | 56 |
94 | 57 | ### Base Protocol
95 | 58 |
96 | 59 | - [JSON-RPC](https://www.jsonrpc.org/) message format
97 | 60 | - Stateful connections
98 | 61 | - Server and client capability negotiation
99 | 62 |
100 | 63 | ### Features
101 | 64 |
102 | 65 | Servers offer any of the following features to clients:
103 | 66 |
104 | 67 | - **Resources**: Context and data, for the user or the AI model to use
105 | 68 | - **Prompts**: Templated messages and workflows for users
106 | 69 | - **Tools**: Functions for the AI model to execute
107 | 70 |
108 | 71 | Clients may offer the following feature to servers:
109 | 72 |
110 | 73 | - **Sampling**: Server-initiated agentic behaviors and recursive LLM interactions
111 | 74 |
112 | 75 | ### Additional Utilities
113 | 76 |
114 | 77 | - Configuration
115 | 78 | - Progress tracking
116 | 79 | - Cancellation
117 | 80 | - Error reporting
118 | 81 | - Logging
119 | 82 |
120 | 83 | ## Security and Trust & Safety
121 | 84 |
122 | 85 | The Model Context Protocol enables powerful capabilities through arbitrary data access
123 | 86 | and code execution paths. With this power comes important security and trust
124 | 87 | considerations that all implementors must carefully address.
125 | 88 |
126 | 89 | ### Key Principles
127 | 90 |
128 | 91 | 1. **User Consent and Control**
129 | 92 |
130 | 93 | - Users must explicitly consent to and understand all data access and operations
131 | 94 | - Users must retain control over what data is shared and what actions are taken
132 | 95 | - Implementors should provide clear UIs for reviewing and authorizing activities
133 | 96 |
134 | 97 | 2. **Data Privacy**
135 | 98 |
136 | 99 | - Hosts must obtain explicit user consent before exposing user data to servers
137 | 100 | - Hosts must not transmit resource data elsewhere without user consent
138 | 101 | - User data should be protected with appropriate access controls
139 | 102 |
140 | 103 | 3. **Tool Safety**
141 | 104 |
142 | 105 | - Tools represent arbitrary code execution and must be treated with appropriate
143 | 106 | caution.
144 | 107 | - In particular, descriptions of tool behavior such as annotations should be
145 | 108 | considered untrusted, unless obtained from a trusted server.
146 | 109 | - Hosts must obtain explicit user consent before invoking any tool
147 | 110 | - Users should understand what each tool does before authorizing its use
148 | 111 |
149 | 112 | 4. **LLM Sampling Controls**
150 | 113 | - Users must explicitly approve any LLM sampling requests
151 | 114 | - Users should control:
152 | 115 | - Whether sampling occurs at all
153 | 116 | - The actual prompt that will be sent
154 | 117 | - What results the server can see
155 | 118 | - The protocol intentionally limits server visibility into prompts
156 | 119 |
157 | 120 | ### Implementation Guidelines
158 | 121 |
159 | 122 | While MCP itself cannot enforce these security principles at the protocol level,
160 | 123 | implementors **SHOULD**:
161 | 124 |
162 | 125 | 1. Build robust consent and authorization flows into their applications
163 | 126 | 2. Provide clear documentation of security implications
164 | 127 | 3. Implement appropriate access controls and data protections
165 | 128 | 4. Follow security best practices in their integrations
166 | 129 | 5. Consider privacy implications in their feature designs
167 | 130 |
168 | 131 | ## Learn More
169 | 132 |
170 | 133 | Explore the detailed specification for each protocol component:
171 | 134 |
172 | 135 | {{< cards >}} {{< card link="architecture" title="Architecture" icon="template" >}}
173 | 136 | {{< card link="basic" title="Base Protocol" icon="code" >}}
174 | 137 | {{< card link="server" title="Server Features" icon="server" >}}
175 | 138 | {{< card link="client" title="Client Features" icon="user" >}}
176 | 139 | {{< card link="contributing" title="Contributing" icon="pencil" >}} {{< /cards >}}
177 | 140 |
178 |
179 |
180 | --------------------------------------------------------------------------------
181 | /docs/specification/2025-03-26/architecture/_index.md:
182 | --------------------------------------------------------------------------------
183 | 1 | ---
184 | 2 | title: Architecture
185 | 3 | cascade:
186 | 4 | type: docs
187 | 5 | weight: 10
188 | 6 | ---
189 | 7 |
190 | 8 | The Model Context Protocol (MCP) follows a client-host-server architecture where each
191 | 9 | host can run multiple client instances. This architecture enables users to integrate AI
192 | 10 | capabilities across applications while maintaining clear security boundaries and
193 | 11 | isolating concerns. Built on JSON-RPC, MCP provides a stateful session protocol focused
194 | 12 | on context exchange and sampling coordination between clients and servers.
195 | 13 |
196 | 14 | ## Core Components
197 | 15 |
198 | 16 | ```mermaid
199 | 17 | graph LR
200 | 18 | subgraph "Application Host Process"
201 | 19 | H[Host]
202 | 20 | C1[Client 1]
203 | 21 | C2[Client 2]
204 | 22 | C3[Client 3]
205 | 23 | H --> C1
206 | 24 | H --> C2
207 | 25 | H --> C3
208 | 26 | end
209 | 27 |
210 | 28 | subgraph "Local machine"
211 | 29 | S1[Server 1<br>Files & Git]
212 | 30 | S2[Server 2<br>Database]
213 | 31 | R1[("Local<br>Resource A")]
214 | 32 | R2[("Local<br>Resource B")]
215 | 33 |
216 | 34 | C1 --> S1
217 | 35 | C2 --> S2
218 | 36 | S1 <--> R1
219 | 37 | S2 <--> R2
220 | 38 | end
221 | 39 |
222 | 40 | subgraph "Internet"
223 | 41 | S3[Server 3<br>External APIs]
224 | 42 | R3[("Remote<br>Resource C")]
225 | 43 |
226 | 44 | C3 --> S3
227 | 45 | S3 <--> R3
228 | 46 | end
229 | 47 | ```
230 | 48 |
231 | 49 | ### Host
232 | 50 |
233 | 51 | The host process acts as the container and coordinator:
234 | 52 |
235 | 53 | - Creates and manages multiple client instances
236 | 54 | - Controls client connection permissions and lifecycle
237 | 55 | - Enforces security policies and consent requirements
238 | 56 | - Handles user authorization decisions
239 | 57 | - Coordinates AI/LLM integration and sampling
240 | 58 | - Manages context aggregation across clients
241 | 59 |
242 | 60 | ### Clients
243 | 61 |
244 | 62 | Each client is created by the host and maintains an isolated server connection:
245 | 63 |
246 | 64 | - Establishes one stateful session per server
247 | 65 | - Handles protocol negotiation and capability exchange
248 | 66 | - Routes protocol messages bidirectionally
249 | 67 | - Manages subscriptions and notifications
250 | 68 | - Maintains security boundaries between servers
251 | 69 |
252 | 70 | A host application creates and manages multiple clients, with each client having a 1:1
253 | 71 | relationship with a particular server.
254 | 72 |
255 | 73 | ### Servers
256 | 74 |
257 | 75 | Servers provide specialized context and capabilities:
258 | 76 |
259 | 77 | - Expose resources, tools and prompts via MCP primitives
260 | 78 | - Operate independently with focused responsibilities
261 | 79 | - Request sampling through client interfaces
262 | 80 | - Must respect security constraints
263 | 81 | - Can be local processes or remote services
264 | 82 |
265 | 83 | ## Design Principles
266 | 84 |
267 | 85 | MCP is built on several key design principles that inform its architecture and
268 | 86 | implementation:
269 | 87 |
270 | 88 | 1. **Servers should be extremely easy to build**
271 | 89 |
272 | 90 | - Host applications handle complex orchestration responsibilities
273 | 91 | - Servers focus on specific, well-defined capabilities
274 | 92 | - Simple interfaces minimize implementation overhead
275 | 93 | - Clear separation enables maintainable code
276 | 94 |
277 | 95 | 2. **Servers should be highly composable**
278 | 96 |
279 | 97 | - Each server provides focused functionality in isolation
280 | 98 | - Multiple servers can be combined seamlessly
281 | 99 | - Shared protocol enables interoperability
282 | 100 | - Modular design supports extensibility
283 | 101 |
284 | 102 | 3. **Servers should not be able to read the whole conversation, nor "see into" other
285 | 103 | servers**
286 | 104 |
287 | 105 | - Servers receive only necessary contextual information
288 | 106 | - Full conversation history stays with the host
289 | 107 | - Each server connection maintains isolation
290 | 108 | - Cross-server interactions are controlled by the host
291 | 109 | - Host process enforces security boundaries
292 | 110 |
293 | 111 | 4. **Features can be added to servers and clients progressively**
294 | 112 | - Core protocol provides minimal required functionality
295 | 113 | - Additional capabilities can be negotiated as needed
296 | 114 | - Servers and clients evolve independently
297 | 115 | - Protocol designed for future extensibility
298 | 116 | - Backwards compatibility is maintained
299 | 117 |
300 | 118 | ## Capability Negotiation
301 | 119 |
302 | 120 | The Model Context Protocol uses a capability-based negotiation system where clients and
303 | 121 | servers explicitly declare their supported features during initialization. Capabilities
304 | 122 | determine which protocol features and primitives are available during a session.
305 | 123 |
306 | 124 | - Servers declare capabilities like resource subscriptions, tool support, and prompt
307 | 125 | templates
308 | 126 | - Clients declare capabilities like sampling support and notification handling
309 | 127 | - Both parties must respect declared capabilities throughout the session
310 | 128 | - Additional capabilities can be negotiated through extensions to the protocol
311 | 129 |
312 | 130 | ```mermaid
313 | 131 | sequenceDiagram
314 | 132 | participant Host
315 | 133 | participant Client
316 | 134 | participant Server
317 | 135 |
318 | 136 | Host->>+Client: Initialize client
319 | 137 | Client->>+Server: Initialize session with capabilities
320 | 138 | Server-->>Client: Respond with supported capabilities
321 | 139 |
322 | 140 | Note over Host,Server: Active Session with Negotiated Features
323 | 141 |
324 | 142 | loop Client Requests
325 | 143 | Host->>Client: User- or model-initiated action
326 | 144 | Client->>Server: Request (tools/resources)
327 | 145 | Server-->>Client: Response
328 | 146 | Client-->>Host: Update UI or respond to model
329 | 147 | end
330 | 148 |
331 | 149 | loop Server Requests
332 | 150 | Server->>Client: Request (sampling)
333 | 151 | Client->>Host: Forward to AI
334 | 152 | Host-->>Client: AI response
335 | 153 | Client-->>Server: Response
336 | 154 | end
337 | 155 |
338 | 156 | loop Notifications
339 | 157 | Server--)Client: Resource updates
340 | 158 | Client--)Server: Status changes
341 | 159 | end
342 | 160 |
343 | 161 | Host->>Client: Terminate
344 | 162 | Client->>-Server: End session
345 | 163 | deactivate Server
346 | 164 | ```
347 | 165 |
348 | 166 | Each capability unlocks specific protocol features for use during the session. For
349 | 167 | example:
350 | 168 |
351 | 169 | - Implemented [server features]({{< ref "../server" >}}) must be advertised in the
352 | 170 | server's capabilities
353 | 171 | - Emitting resource subscription notifications requires the server to declare
354 | 172 | subscription support
355 | 173 | - Tool invocation requires the server to declare tool capabilities
356 | 174 | - [Sampling]({{< ref "../client" >}}) requires the client to declare support in its
357 | 175 | capabilities
358 | 176 |
359 | 177 | This capability negotiation ensures clients and servers have a clear understanding of
360 | 178 | supported functionality while maintaining protocol extensibility.
361 | 179 |
362 |
363 |
364 | --------------------------------------------------------------------------------
365 | /docs/specification/2025-03-26/basic/_index.md:
366 | --------------------------------------------------------------------------------
367 | 1 | ---
368 | 2 | title: Base Protocol
369 | 3 | cascade:
370 | 4 | type: docs
371 | 5 | weight: 20
372 | 6 | ---
373 | 7 |
374 | 8 | {{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}}
375 | 9 |
376 | 10 | The Model Context Protocol consists of several key components that work together:
377 | 11 |
378 | 12 | - **Base Protocol**: Core JSON-RPC message types
379 | 13 | - **Lifecycle Management**: Connection initialization, capability negotiation, and
380 | 14 | session control
381 | 15 | - **Server Features**: Resources, prompts, and tools exposed by servers
382 | 16 | - **Client Features**: Sampling and root directory lists provided by clients
383 | 17 | - **Utilities**: Cross-cutting concerns like logging and argument completion
384 | 18 |
385 | 19 | All implementations **MUST** support the base protocol and lifecycle management
386 | 20 | components. Other components **MAY** be implemented based on the specific needs of the
387 | 21 | application.
388 | 22 |
389 | 23 | These protocol layers establish clear separation of concerns while enabling rich
390 | 24 | interactions between clients and servers. The modular design allows implementations to
391 | 25 | support exactly the features they need.
392 | 26 |
393 | 27 | ## Messages
394 | 28 |
395 | 29 | All messages between MCP clients and servers **MUST** follow the
396 | 30 | [JSON-RPC 2.0](https://www.jsonrpc.org/specification) specification. The protocol defines
397 | 31 | these types of messages:
398 | 32 |
399 | 33 | ### Requests
400 | 34 |
401 | 35 | Requests are sent from the client to the server or vice versa, to initiate an operation.
402 | 36 |
403 | 37 | ```typescript
404 | 38 | {
405 | 39 | jsonrpc: "2.0";
406 | 40 | id: string | number;
407 | 41 | method: string;
408 | 42 | params?: {
409 | 43 | [key: string]: unknown;
410 | 44 | };
411 | 45 | }
412 | 46 | ```
413 | 47 |
414 | 48 | - Requests **MUST** include a string or integer ID.
415 | 49 | - Unlike base JSON-RPC, the ID **MUST NOT** be `null`.
416 | 50 | - The request ID **MUST NOT** have been previously used by the requestor within the same
417 | 51 | session.
418 | 52 |
419 | 53 | ### Responses
420 | 54 |
421 | 55 | Responses are sent in reply to requests, containing the result or error of the operation.
422 | 56 |
423 | 57 | ```typescript
424 | 58 | {
425 | 59 | jsonrpc: "2.0";
426 | 60 | id: string | number;
427 | 61 | result?: {
428 | 62 | [key: string]: unknown;
429 | 63 | }
430 | 64 | error?: {
431 | 65 | code: number;
432 | 66 | message: string;
433 | 67 | data?: unknown;
434 | 68 | }
435 | 69 | }
436 | 70 | ```
437 | 71 |
438 | 72 | - Responses **MUST** include the same ID as the request they correspond to.
439 | 73 | - **Responses** are further sub-categorized as either **successful results** or
440 | 74 | **errors**. Either a `result` or an `error` **MUST** be set. A response **MUST NOT**
441 | 75 | set both.
442 | 76 | - Results **MAY** follow any JSON object structure, while errors **MUST** include an
443 | 77 | error code and message at minimum.
444 | 78 | - Error codes **MUST** be integers.
445 | 79 |
446 | 80 | ### Notifications
447 | 81 |
448 | 82 | Notifications are sent from the client to the server or vice versa, as a one-way message.
449 | 83 | The receiver **MUST NOT** send a response.
450 | 84 |
451 | 85 | ```typescript
452 | 86 | {
453 | 87 | jsonrpc: "2.0";
454 | 88 | method: string;
455 | 89 | params?: {
456 | 90 | [key: string]: unknown;
457 | 91 | };
458 | 92 | }
459 | 93 | ```
460 | 94 |
461 | 95 | - Notifications **MUST NOT** include an ID.
462 | 96 |
463 | 97 | ### Batching
464 | 98 |
465 | 99 | JSON-RPC also defines a means to
466 | 100 | [batch multiple requests and notifications](https://www.jsonrpc.org/specification#batch),
467 | 101 | by sending them in an array. MCP implementations **MAY** support sending JSON-RPC
468 | 102 | batches, but **MUST** support receiving JSON-RPC batches.
469 | 103 |
470 | 104 | ## Auth
471 | 105 |
472 | 106 | MCP provides an [Authorization]({{< ref "authorization" >}}) framework for use with HTTP.
473 | 107 | Implementations using an HTTP-based transport **SHOULD** conform to this specification,
474 | 108 | whereas implementations using STDIO transport **SHOULD NOT** follow this specification,
475 | 109 | and instead retrieve credentials from the environment.
476 | 110 |
477 | 111 | Additionally, clients and servers **MAY** negotiate their own custom authentication and
478 | 112 | authorization strategies.
479 | 113 |
480 | 114 | For further discussions and contributions to the evolution of MCP’s auth mechanisms, join
481 | 115 | us in
482 | 116 | [GitHub Discussions](https://github.com/modelcontextprotocol/specification/discussions)
483 | 117 | to help shape the future of the protocol!
484 | 118 |
485 | 119 | ## Schema
486 | 120 |
487 | 121 | The full specification of the protocol is defined as a
488 | 122 | [TypeScript schema](http://github.com/modelcontextprotocol/specification/tree/main/schema/draft/schema.ts).
489 | 123 | This is the source of truth for all protocol messages and structures.
490 | 124 |
491 | 125 | There is also a
492 | 126 | [JSON Schema](http://github.com/modelcontextprotocol/specification/tree/main/schema/draft/schema.json),
493 | 127 | which is automatically generated from the TypeScript source of truth, for use with
494 | 128 | various automated tooling.
495 | 129 |
496 |
497 |
498 | --------------------------------------------------------------------------------
499 | /docs/specification/2025-03-26/basic/authorization.md:
500 | --------------------------------------------------------------------------------
501 | 1 | ---
502 | 2 | title: Authorization
503 | 3 | type: docs
504 | 4 | weight: 15
505 | 5 | ---
506 | 6 |
507 | 7 | {{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}}
508 | 8 |
509 | 9 | ## 1. Introduction
510 | 10 |
511 | 11 | ### 1.1 Purpose and Scope
512 | 12 |
513 | 13 | The Model Context Protocol provides authorization capabilities at the transport level,
514 | 14 | enabling MCP clients to make requests to restricted MCP servers on behalf of resource
515 | 15 | owners. This specification defines the authorization flow for HTTP-based transports.
516 | 16 |
517 | 17 | ### 1.2 Protocol Requirements
518 | 18 |
519 | 19 | Authorization is **OPTIONAL** for MCP implementations. When supported:
520 | 20 |
521 | 21 | - Implementations using an HTTP-based transport **SHOULD** conform to this specification.
522 | 22 | - Implementations using an STDIO transport **SHOULD NOT** follow this specification, and
523 | 23 | instead retrieve credentials from the environment.
524 | 24 | - Implementations using alternative transports **MUST** follow established security best
525 | 25 | practices for their protocol.
526 | 26 |
527 | 27 | ### 1.3 Standards Compliance
528 | 28 |
529 | 29 | This authorization mechanism is based on established specifications listed below, but
530 | 30 | implements a selected subset of their features to ensure security and interoperability
531 | 31 | while maintaining simplicity:
532 | 32 |
533 | 33 | - [OAuth 2.1 IETF DRAFT](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12)
534 | 34 | - OAuth 2.0 Authorization Server Metadata
535 | 35 | ([RFC8414](https://datatracker.ietf.org/doc/html/rfc8414))
536 | 36 | - OAuth 2.0 Dynamic Client Registration Protocol
537 | 37 | ([RFC7591](https://datatracker.ietf.org/doc/html/rfc7591))
538 | 38 |
539 | 39 | ## 2. Authorization Flow
540 | 40 |
541 | 41 | ### 2.1 Overview
542 | 42 |
543 | 43 | 1. MCP auth implementations **MUST** implement OAuth 2.1 with appropriate security
544 | 44 | measures for both confidential and public clients.
545 | 45 |
546 | 46 | 2. MCP auth implementations **SHOULD** support the OAuth 2.0 Dynamic Client Registration
547 | 47 | Protocol ([RFC7591](https://datatracker.ietf.org/doc/html/rfc7591)).
548 | 48 |
549 | 49 | 3. MCP servers **SHOULD** and MCP clients **MUST** implement OAuth 2.0 Authorization
550 | 50 | Server Metadata ([RFC8414](https://datatracker.ietf.org/doc/html/rfc8414)). Servers
551 | 51 | that do not support Authorization Server Metadata **MUST** follow the default URI
552 | 52 | schema.
553 | 53 |
554 | 54 | ### 2.2 Basic OAuth 2.1 Authorization
555 | 55 |
556 | 56 | When authorization is required and not yet proven by the client, servers **MUST** respond
557 | 57 | with _HTTP 401 Unauthorized_.
558 | 58 |
559 | 59 | Clients initiate the
560 | 60 | [OAuth 2.1 IETF DRAFT](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12)
561 | 61 | authorization flow after receiving the _HTTP 401 Unauthorized_.
562 | 62 |
563 | 63 | The following demonstrates the basic OAuth 2.1 for public clients using PKCE.
564 | 64 |
565 | 65 | ```mermaid
566 | 66 | sequenceDiagram
567 | 67 | participant B as User-Agent (Browser)
568 | 68 | participant C as Client
569 | 69 | participant M as MCP Server
570 | 70 |
571 | 71 | C->>M: MCP Request
572 | 72 | M->>C: HTTP 401 Unauthorized
573 | 73 | Note over C: Generate code_verifier and code_challenge
574 | 74 | C->>B: Open browser with authorization URL + code_challenge
575 | 75 | B->>M: GET /authorize
576 | 76 | Note over M: User logs in and authorizes
577 | 77 | M->>B: Redirect to callback URL with auth code
578 | 78 | B->>C: Callback with authorization code
579 | 79 | C->>M: Token Request with code + code_verifier
580 | 80 | M->>C: Access Token (+ Refresh Token)
581 | 81 | C->>M: MCP Request with Access Token
582 | 82 | Note over C,M: Begin standard MCP message exchange
583 | 83 | ```
584 | 84 |
585 | 85 | ### 2.3 Server Metadata Discovery
586 | 86 |
587 | 87 | For server capability discovery:
588 | 88 |
589 | 89 | - MCP clients _MUST_ follow the OAuth 2.0 Authorization Server Metadata protocol defined
590 | 90 | in [RFC8414](https://datatracker.ietf.org/doc/html/rfc8414).
591 | 91 | - MCP server _SHOULD_ follow the OAuth 2.0 Authorization Server Metadata protocol.
592 | 92 | - MCP servers that do not support the OAuth 2.0 Authorization Server Metadata protocol,
593 | 93 | _MUST_ support fallback URLs.
594 | 94 |
595 | 95 | The discovery flow is illustrated below:
596 | 96 |
597 | 97 | ```mermaid
598 | 98 | sequenceDiagram
599 | 99 | participant C as Client
600 | 100 | participant S as Server
601 | 101 |
602 | 102 | C->>S: GET /.well-known/oauth-authorization-server
603 | 103 | alt Discovery Success
604 | 104 | S->>C: 200 OK + Metadata Document
605 | 105 | Note over C: Use endpoints from metadata
606 | 106 | else Discovery Failed
607 | 107 | S->>C: 404 Not Found
608 | 108 | Note over C: Fall back to default endpoints
609 | 109 | end
610 | 110 | Note over C: Continue with authorization flow
611 | 111 | ```
612 | 112 |
613 | 113 | #### 2.3.1 Server Metadata Discovery Headers
614 | 114 |
615 | 115 | MCP clients _SHOULD_ include the header `MCP-Protocol-Version: <protocol-version>` during
616 | 116 | Server Metadata Discovery to allow the MCP server to respond based on the MCP protocol
617 | 117 | version.
618 | 118 |
619 | 119 | For example: `MCP-Protocol-Version: 2024-11-05`
620 | 120 |
621 | 121 | #### 2.3.2 Authorization Base URL
622 | 122 |
623 | 123 | The authorization base URL **MUST** be determined from the MCP server URL by discarding
624 | 124 | any existing `path` component. For example:
625 | 125 |
626 | 126 | If the MCP server URL is `https://api.example.com/v1/mcp`, then:
627 | 127 |
628 | 128 | - The authorization base URL is `https://api.example.com`
629 | 129 | - The metadata endpoint **MUST** be at
630 | 130 | `https://api.example.com/.well-known/oauth-authorization-server`
631 | 131 |
632 | 132 | This ensures authorization endpoints are consistently located at the root level of the
633 | 133 | domain hosting the MCP server, regardless of any path components in the MCP server URL.
634 | 134 |
635 | 135 | #### 2.3.3 Fallbacks for Servers without Metadata Discovery
636 | 136 |
637 | 137 | For servers that do not implement OAuth 2.0 Authorization Server Metadata, clients
638 | 138 | **MUST** use the following default endpoint paths relative to the authorization base URL
639 | 139 | (as defined in [Section 2.3.2](#232-authorization-base-url)):
640 | 140 |
641 | 141 | | Endpoint | Default Path | Description |
642 | 142 | | ---------------------- | ------------ | ------------------------------------ |
643 | 143 | | Authorization Endpoint | /authorize | Used for authorization requests |
644 | 144 | | Token Endpoint | /token | Used for token exchange & refresh |
645 | 145 | | Registration Endpoint | /register | Used for dynamic client registration |
646 | 146 |
647 | 147 | For example, with an MCP server hosted at `https://api.example.com/v1/mcp`, the default
648 | 148 | endpoints would be:
649 | 149 |
650 | 150 | - `https://api.example.com/authorize`
651 | 151 | - `https://api.example.com/token`
652 | 152 | - `https://api.example.com/register`
653 | 153 |
654 | 154 | Clients **MUST** first attempt to discover endpoints via the metadata document before
655 | 155 | falling back to default paths. When using default paths, all other protocol requirements
656 | 156 | remain unchanged.
657 | 157 |
658 | 158 | ### 2.3 Dynamic Client Registration
659 | 159 |
660 | 160 | MCP clients and servers **SHOULD** support the
661 | 161 | [OAuth 2.0 Dynamic Client Registration Protocol](https://datatracker.ietf.org/doc/html/rfc7591)
662 | 162 | to allow MCP clients to obtain OAuth client IDs without user interaction. This provides a
663 | 163 | standardized way for clients to automatically register with new servers, which is crucial
664 | 164 | for MCP because:
665 | 165 |
666 | 166 | - Clients cannot know all possible servers in advance
667 | 167 | - Manual registration would create friction for users
668 | 168 | - It enables seamless connection to new servers
669 | 169 | - Servers can implement their own registration policies
670 | 170 |
671 | 171 | Any MCP servers that _do not_ support Dynamic Client Registration need to provide
672 | 172 | alternative ways to obtain a client ID (and, if applicable, client secret). For one of
673 | 173 | these servers, MCP clients will have to either:
674 | 174 |
675 | 175 | 1. Hardcode a client ID (and, if applicable, client secret) specifically for that MCP
676 | 176 | server, or
677 | 177 | 2. Present a UI to users that allows them to enter these details, after registering an
678 | 178 | OAuth client themselves (e.g., through a configuration interface hosted by the
679 | 179 | server).
680 | 180 |
681 | 181 | ### 2.4 Authorization Flow Steps
682 | 182 |
683 | 183 | The complete Authorization flow proceeds as follows:
684 | 184 |
685 | 185 | ```mermaid
686 | 186 | sequenceDiagram
687 | 187 | participant B as User-Agent (Browser)
688 | 188 | participant C as Client
689 | 189 | participant M as MCP Server
690 | 190 |
691 | 191 | C->>M: GET /.well-known/oauth-authorization-server
692 | 192 | alt Server Supports Discovery
693 | 193 | M->>C: Authorization Server Metadata
694 | 194 | else No Discovery
695 | 195 | M->>C: 404 (Use default endpoints)
696 | 196 | end
697 | 197 |
698 | 198 | alt Dynamic Client Registration
699 | 199 | C->>M: POST /register
700 | 200 | M->>C: Client Credentials
701 | 201 | end
702 | 202 |
703 | 203 | Note over C: Generate PKCE Parameters
704 | 204 | C->>B: Open browser with authorization URL + code_challenge
705 | 205 | B->>M: Authorization Request
706 | 206 | Note over M: User /authorizes
707 | 207 | M->>B: Redirect to callback with authorization code
708 | 208 | B->>C: Authorization code callback
709 | 209 | C->>M: Token Request + code_verifier
710 | 210 | M->>C: Access Token (+ Refresh Token)
711 | 211 | C->>M: API Requests with Access Token
712 | 212 | ```
713 | 213 |
714 | 214 | #### 2.4.1 Decision Flow Overview
715 | 215 |
716 | 216 | ```mermaid
717 | 217 | flowchart TD
718 | 218 | A[Start Auth Flow] --> B{Check Metadata Discovery}
719 | 219 | B -->|Available| C[Use Metadata Endpoints]
720 | 220 | B -->|Not Available| D[Use Default Endpoints]
721 | 221 |
722 | 222 | C --> G{Check Registration Endpoint}
723 | 223 | D --> G
724 | 224 |
725 | 225 | G -->|Available| H[Perform Dynamic Registration]
726 | 226 | G -->|Not Available| I[Alternative Registration Required]
727 | 227 |
728 | 228 | H --> J[Start OAuth Flow]
729 | 229 | I --> J
730 | 230 |
731 | 231 | J --> K[Generate PKCE Parameters]
732 | 232 | K --> L[Request Authorization]
733 | 233 | L --> M[User Authorization]
734 | 234 | M --> N[Exchange Code for Tokens]
735 | 235 | N --> O[Use Access Token]
736 | 236 | ```
737 | 237 |
738 | 238 | ### 2.5 Access Token Usage
739 | 239 |
740 | 240 | #### 2.5.1 Token Requirements
741 | 241 |
742 | 242 | Access token handling **MUST** conform to
743 | 243 | [OAuth 2.1 Section 5](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5)
744 | 244 | requirements for resource requests. Specifically:
745 | 245 |
746 | 246 | 1. MCP client **MUST** use the Authorization request header field
747 | 247 | [Section 5.1.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.1.1):
748 | 248 |
749 | 249 | ```
750 | 250 | Authorization: Bearer <access-token>
751 | 251 | ```
752 | 252 |
753 | 253 | Note that authorization **MUST** be included in every HTTP request from client to server,
754 | 254 | even if they are part of the same logical session.
755 | 255 |
756 | 256 | 2. Access tokens **MUST NOT** be included in the URI query string
757 | 257 |
758 | 258 | Example request:
759 | 259 |
760 | 260 | ```http
761 | 261 | GET /v1/contexts HTTP/1.1
762 | 262 | Host: mcp.example.com
763 | 263 | Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
764 | 264 | ```
765 | 265 |
766 | 266 | #### 2.5.2 Token Handling
767 | 267 |
768 | 268 | Resource servers **MUST** validate access tokens as described in
769 | 269 | [Section 5.2](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.2).
770 | 270 | If validation fails, servers **MUST** respond according to
771 | 271 | [Section 5.3](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.3)
772 | 272 | error handling requirements. Invalid or expired tokens **MUST** receive a HTTP 401
773 | 273 | response.
774 | 274 |
775 | 275 | ### 2.6 Security Considerations
776 | 276 |
777 | 277 | The following security requirements **MUST** be implemented:
778 | 278 |
779 | 279 | 1. Clients **MUST** securely store tokens following OAuth 2.0 best practices
780 | 280 | 2. Servers **SHOULD** enforce token expiration and rotation
781 | 281 | 3. All authorization endpoints **MUST** be served over HTTPS
782 | 282 | 4. Servers **MUST** validate redirect URIs to prevent open redirect vulnerabilities
783 | 283 | 5. Redirect URIs **MUST** be either localhost URLs or HTTPS URLs
784 | 284 |
785 | 285 | ### 2.7 Error Handling
786 | 286 |
787 | 287 | Servers **MUST** return appropriate HTTP status codes for authorization errors:
788 | 288 |
789 | 289 | | Status Code | Description | Usage |
790 | 290 | | ----------- | ------------ | ------------------------------------------ |
791 | 291 | | 401 | Unauthorized | Authorization required or token invalid |
792 | 292 | | 403 | Forbidden | Invalid scopes or insufficient permissions |
793 | 293 | | 400 | Bad Request | Malformed authorization request |
794 | 294 |
795 | 295 | ### 2.8 Implementation Requirements
796 | 296 |
797 | 297 | 1. Implementations **MUST** follow OAuth 2.1 security best practices
798 | 298 | 2. PKCE is **REQUIRED** for all clients
799 | 299 | 3. Token rotation **SHOULD** be implemented for enhanced security
800 | 300 | 4. Token lifetimes **SHOULD** be limited based on security requirements
801 | 301 |
802 | 302 | ### 2.9 Third-Party Authorization Flow
803 | 303 |
804 | 304 | #### 2.9.1 Overview
805 | 305 |
806 | 306 | MCP servers **MAY** support delegated authorization through third-party authorization
807 | 307 | servers. In this flow, the MCP server acts as both an OAuth client (to the third-party
808 | 308 | auth server) and an OAuth authorization server (to the MCP client).
809 | 309 |
810 | 310 | #### 2.9.2 Flow Description
811 | 311 |
812 | 312 | The third-party authorization flow comprises these steps:
813 | 313 |
814 | 314 | 1. MCP client initiates standard OAuth flow with MCP server
815 | 315 | 2. MCP server redirects user to third-party authorization server
816 | 316 | 3. User authorizes with third-party server
817 | 317 | 4. Third-party server redirects back to MCP server with authorization code
818 | 318 | 5. MCP server exchanges code for third-party access token
819 | 319 | 6. MCP server generates its own access token bound to the third-party session
820 | 320 | 7. MCP server completes original OAuth flow with MCP client
821 | 321 |
822 | 322 | ```mermaid
823 | 323 | sequenceDiagram
824 | 324 | participant B as User-Agent (Browser)
825 | 325 | participant C as MCP Client
826 | 326 | participant M as MCP Server
827 | 327 | participant T as Third-Party Auth Server
828 | 328 |
829 | 329 | C->>M: Initial OAuth Request
830 | 330 | M->>B: Redirect to Third-Party /authorize
831 | 331 | B->>T: Authorization Request
832 | 332 | Note over T: User authorizes
833 | 333 | T->>B: Redirect to MCP Server callback
834 | 334 | B->>M: Authorization code
835 | 335 | M->>T: Exchange code for token
836 | 336 | T->>M: Third-party access token
837 | 337 | Note over M: Generate bound MCP token
838 | 338 | M->>B: Redirect to MCP Client callback
839 | 339 | B->>C: MCP authorization code
840 | 340 | C->>M: Exchange code for token
841 | 341 | M->>C: MCP access token
842 | 342 | ```
843 | 343 |
844 | 344 | #### 2.9.3 Session Binding Requirements
845 | 345 |
846 | 346 | MCP servers implementing third-party authorization **MUST**:
847 | 347 |
848 | 348 | 1. Maintain secure mapping between third-party tokens and issued MCP tokens
849 | 349 | 2. Validate third-party token status before honoring MCP tokens
850 | 350 | 3. Implement appropriate token lifecycle management
851 | 351 | 4. Handle third-party token expiration and renewal
852 | 352 |
853 | 353 | #### 2.9.4 Security Considerations
854 | 354 |
855 | 355 | When implementing third-party authorization, servers **MUST**:
856 | 356 |
857 | 357 | 1. Validate all redirect URIs
858 | 358 | 2. Securely store third-party credentials
859 | 359 | 3. Implement appropriate session timeout handling
860 | 360 | 4. Consider security implications of token chaining
861 | 361 | 5. Implement proper error handling for third-party auth failures
862 | 362 |
863 | 363 | ## 3. Best Practices
864 | 364 |
865 | 365 | #### 3.1 Local clients as Public OAuth 2.1 Clients
866 | 366 |
867 | 367 | We strongly recommend that local clients implement OAuth 2.1 as a public client:
868 | 368 |
869 | 369 | 1. Utilizing code challenges (PKCE) for authorization requests to prevent interception
870 | 370 | attacks
871 | 371 | 2. Implementing secure token storage appropriate for the local system
872 | 372 | 3. Following token refresh best practices to maintain sessions
873 | 373 | 4. Properly handling token expiration and renewal
874 | 374 |
875 | 375 | #### 3.2 Authorization Metadata Discovery
876 | 376 |
877 | 377 | We strongly recommend that all clients implement metadata discovery. This reduces the
878 | 378 | need for users to provide endpoints manually or clients to fallback to the defined
879 | 379 | defaults.
880 | 380 |
881 | 381 | #### 3.3 Dynamic Client Registration
882 | 382 |
883 | 383 | Since clients do not know the set of MCP servers in advance, we strongly recommend the
884 | 384 | implementation of dynamic client registration. This allows applications to automatically
885 | 385 | register with the MCP server, and removes the need for users to obtain client ids
886 | 386 | manually.
887 | 387 |
888 |
889 |
890 | --------------------------------------------------------------------------------
891 | /docs/specification/2025-03-26/basic/lifecycle.md:
892 | --------------------------------------------------------------------------------
893 | 1 | ---
894 | 2 | title: Lifecycle
895 | 3 | type: docs
896 | 4 | weight: 30
897 | 5 | ---
898 | 6 |
899 | 7 | {{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}}
900 | 8 |
901 | 9 | The Model Context Protocol (MCP) defines a rigorous lifecycle for client-server
902 | 10 | connections that ensures proper capability negotiation and state management.
903 | 11 |
904 | 12 | 1. **Initialization**: Capability negotiation and protocol version agreement
905 | 13 | 2. **Operation**: Normal protocol communication
906 | 14 | 3. **Shutdown**: Graceful termination of the connection
907 | 15 |
908 | 16 | ```mermaid
909 | 17 | sequenceDiagram
910 | 18 | participant Client
911 | 19 | participant Server
912 | 20 |
913 | 21 | Note over Client,Server: Initialization Phase
914 | 22 | activate Client
915 | 23 | Client->>+Server: initialize request
916 | 24 | Server-->>Client: initialize response
917 | 25 | Client--)Server: initialized notification
918 | 26 |
919 | 27 | Note over Client,Server: Operation Phase
920 | 28 | rect rgb(200, 220, 250)
921 | 29 | note over Client,Server: Normal protocol operations
922 | 30 | end
923 | 31 |
924 | 32 | Note over Client,Server: Shutdown
925 | 33 | Client--)-Server: Disconnect
926 | 34 | deactivate Server
927 | 35 | Note over Client,Server: Connection closed
928 | 36 | ```
929 | 37 |
930 | 38 | ## Lifecycle Phases
931 | 39 |
932 | 40 | ### Initialization
933 | 41 |
934 | 42 | The initialization phase **MUST** be the first interaction between client and server.
935 | 43 | During this phase, the client and server:
936 | 44 |
937 | 45 | - Establish protocol version compatibility
938 | 46 | - Exchange and negotiate capabilities
939 | 47 | - Share implementation details
940 | 48 |
941 | 49 | The client **MUST** initiate this phase by sending an `initialize` request containing:
942 | 50 |
943 | 51 | - Protocol version supported
944 | 52 | - Client capabilities
945 | 53 | - Client implementation information
946 | 54 |
947 | 55 | ```json
948 | 56 | {
949 | 57 | "jsonrpc": "2.0",
950 | 58 | "id": 1,
951 | 59 | "method": "initialize",
952 | 60 | "params": {
953 | 61 | "protocolVersion": "2024-11-05",
954 | 62 | "capabilities": {
955 | 63 | "roots": {
956 | 64 | "listChanged": true
957 | 65 | },
958 | 66 | "sampling": {}
959 | 67 | },
960 | 68 | "clientInfo": {
961 | 69 | "name": "ExampleClient",
962 | 70 | "version": "1.0.0"
963 | 71 | }
964 | 72 | }
965 | 73 | }
966 | 74 | ```
967 | 75 |
968 | 76 | The initialize request **MUST NOT** be part of a JSON-RPC
969 | 77 | [batch](https://www.jsonrpc.org/specification#batch), as other requests and notifications
970 | 78 | are not possible until initialization has completed. This also permits backwards
971 | 79 | compatibility with prior protocol versions that do not explicitly support JSON-RPC
972 | 80 | batches.
973 | 81 |
974 | 82 | The server **MUST** respond with its own capabilities and information:
975 | 83 |
976 | 84 | ```json
977 | 85 | {
978 | 86 | "jsonrpc": "2.0",
979 | 87 | "id": 1,
980 | 88 | "result": {
981 | 89 | "protocolVersion": "2024-11-05",
982 | 90 | "capabilities": {
983 | 91 | "logging": {},
984 | 92 | "prompts": {
985 | 93 | "listChanged": true
986 | 94 | },
987 | 95 | "resources": {
988 | 96 | "subscribe": true,
989 | 97 | "listChanged": true
990 | 98 | },
991 | 99 | "tools": {
992 | 100 | "listChanged": true
993 | 101 | }
994 | 102 | },
995 | 103 | "serverInfo": {
996 | 104 | "name": "ExampleServer",
997 | 105 | "version": "1.0.0"
998 | 106 | }
999 | 107 | }
1000 | 108 | }
1001 | 109 | ```
1002 | 110 |
1003 | 111 | After successful initialization, the client **MUST** send an `initialized` notification
1004 | 112 | to indicate it is ready to begin normal operations:
1005 | 113 |
1006 | 114 | ```json
1007 | 115 | {
1008 | 116 | "jsonrpc": "2.0",
1009 | 117 | "method": "notifications/initialized"
1010 | 118 | }
1011 | 119 | ```
1012 | 120 |
1013 | 121 | - The client **SHOULD NOT** send requests other than
1014 | 122 | [pings]({{< ref "utilities/ping" >}}) before the server has responded to the
1015 | 123 | `initialize` request.
1016 | 124 | - The server **SHOULD NOT** send requests other than
1017 | 125 | [pings]({{< ref "utilities/ping" >}}) and
1018 | 126 | [logging]({{< ref "../server/utilities/logging" >}}) before receiving the `initialized`
1019 | 127 | notification.
1020 | 128 |
1021 | 129 | #### Version Negotiation
1022 | 130 |
1023 | 131 | In the `initialize` request, the client **MUST** send a protocol version it supports.
1024 | 132 | This **SHOULD** be the _latest_ version supported by the client.
1025 | 133 |
1026 | 134 | If the server supports the requested protocol version, it **MUST** respond with the same
1027 | 135 | version. Otherwise, the server **MUST** respond with another protocol version it
1028 | 136 | supports. This **SHOULD** be the _latest_ version supported by the server.
1029 | 137 |
1030 | 138 | If the client does not support the version in the server's response, it **SHOULD**
1031 | 139 | disconnect.
1032 | 140 |
1033 | 141 | #### Capability Negotiation
1034 | 142 |
1035 | 143 | Client and server capabilities establish which optional protocol features will be
1036 | 144 | available during the session.
1037 | 145 |
1038 | 146 | Key capabilities include:
1039 | 147 |
1040 | 148 | | Category | Capability | Description |
1041 | 149 | | -------- | -------------- | -------------------------------------------------------------------------- |
1042 | 150 | | Client | `roots` | Ability to provide filesystem [roots]({{< ref "../client/roots" >}}) |
1043 | 151 | | Client | `sampling` | Support for LLM [sampling]({{< ref "../client/sampling" >}}) requests |
1044 | 152 | | Client | `experimental` | Describes support for non-standard experimental features |
1045 | 153 | | Server | `prompts` | Offers [prompt templates]({{< ref "../server/prompts" >}}) |
1046 | 154 | | Server | `resources` | Provides readable [resources]({{< ref "../server/resources" >}}) |
1047 | 155 | | Server | `tools` | Exposes callable [tools]({{< ref "../server/tools" >}}) |
1048 | 156 | | Server | `logging` | Emits structured [log messages]({{< ref "../server/utilities/logging" >}}) |
1049 | 157 | | Server | `experimental` | Describes support for non-standard experimental features |
1050 | 158 |
1051 | 159 | Capability objects can describe sub-capabilities like:
1052 | 160 |
1053 | 161 | - `listChanged`: Support for list change notifications (for prompts, resources, and
1054 | 162 | tools)
1055 | 163 | - `subscribe`: Support for subscribing to individual items' changes (resources only)
1056 | 164 |
1057 | 165 | ### Operation
1058 | 166 |
1059 | 167 | During the operation phase, the client and server exchange messages according to the
1060 | 168 | negotiated capabilities.
1061 | 169 |
1062 | 170 | Both parties **SHOULD**:
1063 | 171 |
1064 | 172 | - Respect the negotiated protocol version
1065 | 173 | - Only use capabilities that were successfully negotiated
1066 | 174 |
1067 | 175 | ### Shutdown
1068 | 176 |
1069 | 177 | During the shutdown phase, one side (usually the client) cleanly terminates the protocol
1070 | 178 | connection. No specific shutdown messages are defined—instead, the underlying transport
1071 | 179 | mechanism should be used to signal connection termination:
1072 | 180 |
1073 | 181 | #### stdio
1074 | 182 |
1075 | 183 | For the stdio [transport]({{< ref "transports" >}}), the client **SHOULD** initiate
1076 | 184 | shutdown by:
1077 | 185 |
1078 | 186 | 1. First, closing the input stream to the child process (the server)
1079 | 187 | 2. Waiting for the server to exit, or sending `SIGTERM` if the server does not exit
1080 | 188 | within a reasonable time
1081 | 189 | 3. Sending `SIGKILL` if the server does not exit within a reasonable time after `SIGTERM`
1082 | 190 |
1083 | 191 | The server **MAY** initiate shutdown by closing its output stream to the client and
1084 | 192 | exiting.
1085 | 193 |
1086 | 194 | #### HTTP
1087 | 195 |
1088 | 196 | For HTTP [transports]({{< ref "transports" >}}), shutdown is indicated by closing the
1089 | 197 | associated HTTP connection(s).
1090 | 198 |
1091 | 199 | ## Timeouts
1092 | 200 |
1093 | 201 | Implementations **SHOULD** establish timeouts for all sent requests, to prevent hung
1094 | 202 | connections and resource exhaustion. When the request has not received a success or error
1095 | 203 | response within the timeout period, the sender **SHOULD** issue a [cancellation
1096 | 204 | notification]({{< ref "utilities/cancellation" >}}) for that request and stop waiting for
1097 | 205 | a response.
1098 | 206 |
1099 | 207 | SDKs and other middleware **SHOULD** allow these timeouts to be configured on a
1100 | 208 | per-request basis.
1101 | 209 |
1102 | 210 | Implementations **MAY** choose to reset the timeout clock when receiving a [progress
1103 | 211 | notification]({{< ref "utilities/progress" >}}) corresponding to the request, as this
1104 | 212 | implies that work is actually happening. However, implementations **SHOULD** always
1105 | 213 | enforce a maximum timeout, regardless of progress notifications, to limit the impact of a
1106 | 214 | misbehaving client or server.
1107 | 215 |
1108 | 216 | ## Error Handling
1109 | 217 |
1110 | 218 | Implementations **SHOULD** be prepared to handle these error cases:
1111 | 219 |
1112 | 220 | - Protocol version mismatch
1113 | 221 | - Failure to negotiate required capabilities
1114 | 222 | - Request [timeouts](#timeouts)
1115 | 223 |
1116 | 224 | Example initialization error:
1117 | 225 |
1118 | 226 | ```json
1119 | 227 | {
1120 | 228 | "jsonrpc": "2.0",
1121 | 229 | "id": 1,
1122 | 230 | "error": {
1123 | 231 | "code": -32602,
1124 | 232 | "message": "Unsupported protocol version",
1125 | 233 | "data": {
1126 | 234 | "supported": ["2024-11-05"],
1127 | 235 | "requested": "1.0.0"
1128 | 236 | }
1129 | 237 | }
1130 | 238 | }
1131 | 239 | ```
1132 | 240 |
1133 |
1134 |
1135 | --------------------------------------------------------------------------------
1136 | /docs/specification/2025-03-26/basic/transports.md:
1137 | --------------------------------------------------------------------------------
1138 | 1 | ---
1139 | 2 | title: Transports
1140 | 3 | type: docs
1141 | 4 | weight: 10
1142 | 5 | ---
1143 | 6 |
1144 | 7 | {{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}}
1145 | 8 |
1146 | 9 | MCP uses JSON-RPC to encode messages. JSON-RPC messages **MUST** be UTF-8 encoded.
1147 | 10 |
1148 | 11 | The protocol currently defines two standard transport mechanisms for client-server
1149 | 12 | communication:
1150 | 13 |
1151 | 14 | 1. [stdio](#stdio), communication over standard in and standard out
1152 | 15 | 2. [Streamable HTTP](#streamable-http)
1153 | 16 |
1154 | 17 | Clients **SHOULD** support stdio whenever possible.
1155 | 18 |
1156 | 19 | It is also possible for clients and servers to implement
1157 | 20 | [custom transports](#custom-transports) in a pluggable fashion.
1158 | 21 |
1159 | 22 | ## stdio
1160 | 23 |
1161 | 24 | In the **stdio** transport:
1162 | 25 |
1163 | 26 | - The client launches the MCP server as a subprocess.
1164 | 27 | - The server reads JSON-RPC messages from its standard input (`stdin`) and sends messages
1165 | 28 | to its standard output (`stdout`).
1166 | 29 | - Messages may be JSON-RPC requests, notifications, responses—or a JSON-RPC
1167 | 30 | [batch](https://www.jsonrpc.org/specification#batch) containing one or more requests
1168 | 31 | and/or notifications.
1169 | 32 | - Messages are delimited by newlines, and **MUST NOT** contain embedded newlines.
1170 | 33 | - The server **MAY** write UTF-8 strings to its standard error (`stderr`) for logging
1171 | 34 | purposes. Clients **MAY** capture, forward, or ignore this logging.
1172 | 35 | - The server **MUST NOT** write anything to its `stdout` that is not a valid MCP message.
1173 | 36 | - The client **MUST NOT** write anything to the server's `stdin` that is not a valid MCP
1174 | 37 | message.
1175 | 38 |
1176 | 39 | ```mermaid
1177 | 40 | sequenceDiagram
1178 | 41 | participant Client
1179 | 42 | participant Server Process
1180 | 43 |
1181 | 44 | Client->>+Server Process: Launch subprocess
1182 | 45 | loop Message Exchange
1183 | 46 | Client->>Server Process: Write to stdin
1184 | 47 | Server Process->>Client: Write to stdout
1185 | 48 | Server Process--)Client: Optional logs on stderr
1186 | 49 | end
1187 | 50 | Client->>Server Process: Close stdin, terminate subprocess
1188 | 51 | deactivate Server Process
1189 | 52 | ```
1190 | 53 |
1191 | 54 | ## Streamable HTTP
1192 | 55 |
1193 | 56 | {{< callout type="info" >}} This replaces the [HTTP+SSE
1194 | 57 | transport]({{< ref "/specification/2024-11-05/basic/transports#http-with-sse" >}}) from
1195 | 58 | protocol version 2024-11-05. See the [backwards compatibility](#backwards-compatibility)
1196 | 59 | guide below. {{< /callout >}}
1197 | 60 |
1198 | 61 | In the **Streamable HTTP** transport, the server operates as an independent process that
1199 | 62 | can handle multiple client connections. This transport uses HTTP POST and GET requests.
1200 | 63 | Server can optionally make use of
1201 | 64 | [Server-Sent Events](https://en.wikipedia.org/wiki/Server-sent_events) (SSE) to stream
1202 | 65 | multiple server messages. This permits basic MCP servers, as well as more feature-rich
1203 | 66 | servers supporting streaming and server-to-client notifications and requests.
1204 | 67 |
1205 | 68 | The server **MUST** provide a single HTTP endpoint path (hereafter referred to as the
1206 | 69 | **MCP endpoint**) that supports both POST and GET methods. For example, this could be a
1207 | 70 | URL like `https://example.com/mcp`.
1208 | 71 |
1209 | 72 | ### Sending Messages to the Server
1210 | 73 |
1211 | 74 | Every JSON-RPC message sent from the client **MUST** be a new HTTP POST request to the
1212 | 75 | MCP endpoint.
1213 | 76 |
1214 | 77 | 1. The client **MUST** use HTTP POST to send JSON-RPC messages to the MCP endpoint.
1215 | 78 | 2. The client **MUST** include an `Accept` header, listing both `application/json` and
1216 | 79 | `text/event-stream` as supported content types.
1217 | 80 | 3. The body of the POST request **MUST** be one of the following:
1218 | 81 | - A single JSON-RPC _request_, _notification_, or _response_
1219 | 82 | - An array [batching](https://www.jsonrpc.org/specification#batch) one or more
1220 | 83 | _requests and/or notifications_
1221 | 84 | - An array [batching](https://www.jsonrpc.org/specification#batch) one or more
1222 | 85 | _responses_
1223 | 86 | 4. If the input consists solely of (any number of) JSON-RPC _responses_ or
1224 | 87 | _notifications_:
1225 | 88 | - If the server accepts the input, the server **MUST** return HTTP status code 202
1226 | 89 | Accepted with no body.
1227 | 90 | - If the server cannot accept the input, it **MUST** return an HTTP error status code
1228 | 91 | (e.g., 400 Bad Request). The HTTP response body **MAY** comprise a JSON-RPC _error
1229 | 92 | response_ that has no `id`.
1230 | 93 | 5. If the input contains any number of JSON-RPC _requests_, the server **MUST** either
1231 | 94 | return `Content-Type: text/event-stream`, to initiate an SSE stream, or
1232 | 95 | `Content-Type: application/json`, to return one JSON object. The client **MUST**
1233 | 96 | support both these cases.
1234 | 97 | 6. If the server initiates an SSE stream:
1235 | 98 | - The SSE stream **SHOULD** eventually include one JSON-RPC _response_ per each
1236 | 99 | JSON-RPC _request_ sent in the POST body. These _responses_ **MAY** be
1237 | 100 | [batched](https://www.jsonrpc.org/specification#batch).
1238 | 101 | - The server **MAY** send JSON-RPC _requests_ and _notifications_ before sending a
1239 | 102 | JSON-RPC _response_. These messages **SHOULD** relate to the originating client
1240 | 103 | _request_. These _requests_ and _notifications_ **MAY** be
1241 | 104 | [batched](https://www.jsonrpc.org/specification#batch).
1242 | 105 | - The server **SHOULD NOT** close the SSE stream before sending a JSON-RPC _response_
1243 | 106 | per each received JSON-RPC _request_, unless the [session](#session-management)
1244 | 107 | expires.
1245 | 108 | - After all JSON-RPC _responses_ have been sent, the server **SHOULD** close the SSE
1246 | 109 | stream.
1247 | 110 | - Disconnection **MAY** occur at any time (e.g., due to network conditions).
1248 | 111 | Therefore:
1249 | 112 | - Disconnection **SHOULD NOT** be interpreted as the client cancelling its request.
1250 | 113 | - To cancel, the client **SHOULD** explicitly send an MCP `CancelledNotification`.
1251 | 114 | - To avoid message loss due to disconnection, the server **MAY** make the stream
1252 | 115 | [resumable](#resumability-and-redelivery).
1253 | 116 |
1254 | 117 | ### Listening for Messages from the Server
1255 | 118 |
1256 | 119 | 1. The client **MAY** issue an HTTP GET to the MCP endpoint. This can be used to open an
1257 | 120 | SSE stream, allowing the server to communicate to the client, without the client first
1258 | 121 | sending data via HTTP POST.
1259 | 122 | 2. The client **MUST** include an `Accept` header, listing `text/event-stream` as a
1260 | 123 | supported content type.
1261 | 124 | 3. The server **MUST** either return `Content-Type: text/event-stream` in response to
1262 | 125 | this HTTP GET, or else return HTTP 405 Method Not Allowed, indicating that the server
1263 | 126 | does not offer an SSE stream at this endpoint.
1264 | 127 | 4. If the server initiates an SSE stream:
1265 | 128 | - The server **MAY** send JSON-RPC _requests_ and _notifications_ on the stream. These
1266 | 129 | _requests_ and _notifications_ **MAY** be
1267 | 130 | [batched](https://www.jsonrpc.org/specification#batch).
1268 | 131 | - These messages **SHOULD** be unrelated to any concurrently-running JSON-RPC
1269 | 132 | _request_ from the client.
1270 | 133 | - The server **MUST NOT** send a JSON-RPC _response_ on the stream **unless**
1271 | 134 | [resuming](#resumability-and-redelivery) a stream associated with a previous client
1272 | 135 | request.
1273 | 136 | - The server **MAY** close the SSE stream at any time.
1274 | 137 | - The client **MAY** close the SSE stream at any time.
1275 | 138 |
1276 | 139 | ### Multiple Connections
1277 | 140 |
1278 | 141 | 1. The client **MAY** remain connected to multiple SSE streams simultaneously.
1279 | 142 | 2. The server **MUST** send each of its JSON-RPC messages on only one of the connected
1280 | 143 | streams; that is, it **MUST NOT** broadcast the same message across multiple streams.
1281 | 144 | - The risk of message loss **MAY** be mitigated by making the stream
1282 | 145 | [resumable](#resumability-and-redelivery).
1283 | 146 |
1284 | 147 | ### Resumability and Redelivery
1285 | 148 |
1286 | 149 | To support resuming broken connections, and redelivering messages that might otherwise be
1287 | 150 | lost:
1288 | 151 |
1289 | 152 | 1. Servers **MAY** attach an `id` field to their SSE events, as described in the
1290 | 153 | [SSE standard](https://html.spec.whatwg.org/multipage/server-sent-events.html#event-stream-interpretation).
1291 | 154 | - If present, the ID **MUST** be globally unique across all streams within that
1292 | 155 | [session](#session-management)—or all streams with that specific client, if session
1293 | 156 | management is not in use.
1294 | 157 | 2. If the client wishes to resume after a broken connection, it **SHOULD** issue an HTTP
1295 | 158 | GET to the MCP endpoint, and include the
1296 | 159 | [`Last-Event-ID`](https://html.spec.whatwg.org/multipage/server-sent-events.html#the-last-event-id-header)
1297 | 160 | header to indicate the last event ID it received.
1298 | 161 | - The server **MAY** use this header to replay messages that would have been sent
1299 | 162 | after the last event ID, _on the stream that was disconnected_, and to resume the
1300 | 163 | stream from that point.
1301 | 164 | - The server **MUST NOT** replay messages that would have been delivered on a
1302 | 165 | different stream.
1303 | 166 |
1304 | 167 | In other words, these event IDs should be assigned by servers on a _per-stream_ basis, to
1305 | 168 | act as a cursor within that particular stream.
1306 | 169 |
1307 | 170 | ### Session Management
1308 | 171 |
1309 | 172 | An MCP "session" consists of logically related interactions between a client and a
1310 | 173 | server, beginning with the [initialization phase]({{< ref "lifecycle" >}}). To support
1311 | 174 | servers which want to establish stateful sessions:
1312 | 175 |
1313 | 176 | 1. A server using the Streamable HTTP transport **MAY** assign a session ID at
1314 | 177 | initialization time, by including it in an `Mcp-Session-Id` header on the HTTP
1315 | 178 | response containing the `InitializeResult`.
1316 | 179 | - The session ID **SHOULD** be globally unique and cryptographically secure (e.g., a
1317 | 180 | securely generated UUID, a JWT, or a cryptographic hash).
1318 | 181 | - The session ID **MUST** only contain visible ASCII characters (ranging from 0x21 to
1319 | 182 | 0x7E).
1320 | 183 | 2. If an `Mcp-Session-Id` is returned by the server during initialization, clients using
1321 | 184 | the Streamable HTTP transport **MUST** include it in the `Mcp-Session-Id` header on
1322 | 185 | all of their subsequent HTTP requests.
1323 | 186 | - Servers that require a session ID **SHOULD** respond to requests without an
1324 | 187 | `Mcp-Session-Id` header (other than initialization) with HTTP 400 Bad Request.
1325 | 188 | 3. The server **MAY** terminate the session at any time, after which it **MUST** respond
1326 | 189 | to requests containing that session ID with HTTP 404 Not Found.
1327 | 190 | 4. When a client receives HTTP 404 in response to a request containing an
1328 | 191 | `Mcp-Session-Id`, it **MUST** start a new session by sending a new `InitializeRequest`
1329 | 192 | without a session ID attached.
1330 | 193 | 5. Clients that no longer need a particular session (e.g., because the user is leaving
1331 | 194 | the client application) **SHOULD** send an HTTP DELETE to the MCP endpoint with the
1332 | 195 | `Mcp-Session-Id` header, to explicitly terminate the session.
1333 | 196 | - The server **MAY** respond to this request with HTTP 405 Method Not Allowed,
1334 | 197 | indicating that the server does not allow clients to terminate sessions.
1335 | 198 |
1336 | 199 | ### Sequence Diagram
1337 | 200 |
1338 | 201 | ```mermaid
1339 | 202 | sequenceDiagram
1340 | 203 | participant Client
1341 | 204 | participant Server
1342 | 205 |
1343 | 206 | note over Client, Server: initialization
1344 | 207 |
1345 | 208 | Client->>+Server: POST InitializeRequest
1346 | 209 | Server->>-Client: InitializeResponse<br>Mcp-Session-Id: 1868a90c...
1347 | 210 |
1348 | 211 | Client->>+Server: POST InitializedNotification<br>Mcp-Session-Id: 1868a90c...
1349 | 212 | Server->>-Client: 202 Accepted
1350 | 213 |
1351 | 214 | note over Client, Server: client requests
1352 | 215 | Client->>+Server: POST ... request ...<br>Mcp-Session-Id: 1868a90c...
1353 | 216 |
1354 | 217 | alt single HTTP response
1355 | 218 | Server->>Client: ... response ...
1356 | 219 | else server opens SSE stream
1357 | 220 | loop while connection remains open
1358 | 221 | Server-)Client: ... SSE messages from server ...
1359 | 222 | end
1360 | 223 | Server-)Client: SSE event: ... response ...
1361 | 224 | end
1362 | 225 | deactivate Server
1363 | 226 |
1364 | 227 | note over Client, Server: client notifications/responses
1365 | 228 | Client->>+Server: POST ... notification/response ...<br>Mcp-Session-Id: 1868a90c...
1366 | 229 | Server->>-Client: 202 Accepted
1367 | 230 |
1368 | 231 | note over Client, Server: server requests
1369 | 232 | Client->>+Server: GET<br>Mcp-Session-Id: 1868a90c...
1370 | 233 | loop while connection remains open
1371 | 234 | Server-)Client: ... SSE messages from server ...
1372 | 235 | end
1373 | 236 | deactivate Server
1374 | 237 |
1375 | 238 | ```
1376 | 239 |
1377 | 240 | ### Backwards Compatibility
1378 | 241 |
1379 | 242 | Clients and servers can maintain backwards compatibility with the deprecated [HTTP+SSE
1380 | 243 | transport]({{< ref "/specification/2024-11-05/basic/transports#http-with-sse" >}}) (from
1381 | 244 | protocol version 2024-11-05) as follows:
1382 | 245 |
1383 | 246 | **Servers** wanting to support older clients should:
1384 | 247 |
1385 | 248 | - Continue to host both the SSE and POST endpoints of the old transport, alongside the
1386 | 249 | new "MCP endpoint" defined for the Streamable HTTP transport.
1387 | 250 | - It is also possible to combine the old POST endpoint and the new MCP endpoint, but
1388 | 251 | this may introduce unneeded complexity.
1389 | 252 |
1390 | 253 | **Clients** wanting to support older servers should:
1391 | 254 |
1392 | 255 | 1. Accept an MCP server URL from the user, which may point to either a server using the
1393 | 256 | old transport or the new transport.
1394 | 257 | 2. Attempt to POST an `InitializeRequest` to the server URL, with an `Accept` header as
1395 | 258 | defined above:
1396 | 259 | - If it succeeds, the client can assume this is a server supporting the new Streamable
1397 | 260 | HTTP transport.
1398 | 261 | - If it fails with an HTTP 4xx status code (e.g., 405 Method Not Allowed or 404 Not
1399 | 262 | Found):
1400 | 263 | - Issue a GET request to the server URL, expecting that this will open an SSE stream
1401 | 264 | and return an `endpoint` event as the first event.
1402 | 265 | - When the `endpoint` event arrives, the client can assume this is a server running
1403 | 266 | the old HTTP+SSE transport, and should use that transport for all subsequent
1404 | 267 | communication.
1405 | 268 |
1406 | 269 | ## Custom Transports
1407 | 270 |
1408 | 271 | Clients and servers **MAY** implement additional custom transport mechanisms to suit
1409 | 272 | their specific needs. The protocol is transport-agnostic and can be implemented over any
1410 | 273 | communication channel that supports bidirectional message exchange.
1411 | 274 |
1412 | 275 | Implementers who choose to support custom transports **MUST** ensure they preserve the
1413 | 276 | JSON-RPC message format and lifecycle requirements defined by MCP. Custom transports
1414 | 277 | **SHOULD** document their specific connection establishment and message exchange patterns
1415 | 278 | to aid interoperability.
1416 | 279 |
1417 |
1418 |
1419 | --------------------------------------------------------------------------------
1420 | /docs/specification/2025-03-26/basic/utilities/_index.md:
1421 | --------------------------------------------------------------------------------
1422 | 1 | ---
1423 | 2 | title: Utilities
1424 | 3 | ---
1425 | 4 |
1426 | 5 | {{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}}
1427 | 6 |
1428 | 7 | These optional features enhance the base protocol functionality with various utilities.
1429 | 8 |
1430 | 9 | {{< cards >}} {{< card link="ping" title="Ping" icon="status-online" >}}
1431 | 10 | {{< card link="cancellation" title="Cancellation" icon="x" >}}
1432 | 11 | {{< card link="progress" title="Progress" icon="clock" >}} {{< /cards >}}
1433 | 12 |
1434 |
1435 |
1436 | --------------------------------------------------------------------------------
1437 | /docs/specification/2025-03-26/basic/utilities/cancellation.md:
1438 | --------------------------------------------------------------------------------
1439 | 1 | ---
1440 | 2 | title: Cancellation
1441 | 3 | weight: 10
1442 | 4 | ---
1443 | 5 |
1444 | 6 | {{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}}
1445 | 7 |
1446 | 8 | The Model Context Protocol (MCP) supports optional cancellation of in-progress requests
1447 | 9 | through notification messages. Either side can send a cancellation notification to
1448 | 10 | indicate that a previously-issued request should be terminated.
1449 | 11 |
1450 | 12 | ## Cancellation Flow
1451 | 13 |
1452 | 14 | When a party wants to cancel an in-progress request, it sends a `notifications/cancelled`
1453 | 15 | notification containing:
1454 | 16 |
1455 | 17 | - The ID of the request to cancel
1456 | 18 | - An optional reason string that can be logged or displayed
1457 | 19 |
1458 | 20 | ```json
1459 | 21 | {
1460 | 22 | "jsonrpc": "2.0",
1461 | 23 | "method": "notifications/cancelled",
1462 | 24 | "params": {
1463 | 25 | "requestId": "123",
1464 | 26 | "reason": "User requested cancellation"
1465 | 27 | }
1466 | 28 | }
1467 | 29 | ```
1468 | 30 |
1469 | 31 | ## Behavior Requirements
1470 | 32 |
1471 | 33 | 1. Cancellation notifications **MUST** only reference requests that:
1472 | 34 | - Were previously issued in the same direction
1473 | 35 | - Are believed to still be in-progress
1474 | 36 | 2. The `initialize` request **MUST NOT** be cancelled by clients
1475 | 37 | 3. Receivers of cancellation notifications **SHOULD**:
1476 | 38 | - Stop processing the cancelled request
1477 | 39 | - Free associated resources
1478 | 40 | - Not send a response for the cancelled request
1479 | 41 | 4. Receivers **MAY** ignore cancellation notifications if:
1480 | 42 | - The referenced request is unknown
1481 | 43 | - Processing has already completed
1482 | 44 | - The request cannot be cancelled
1483 | 45 | 5. The sender of the cancellation notification **SHOULD** ignore any response to the
1484 | 46 | request that arrives afterward
1485 | 47 |
1486 | 48 | ## Timing Considerations
1487 | 49 |
1488 | 50 | Due to network latency, cancellation notifications may arrive after request processing
1489 | 51 | has completed, and potentially after a response has already been sent.
1490 | 52 |
1491 | 53 | Both parties **MUST** handle these race conditions gracefully:
1492 | 54 |
1493 | 55 | ```mermaid
1494 | 56 | sequenceDiagram
1495 | 57 | participant Client
1496 | 58 | participant Server
1497 | 59 |
1498 | 60 | Client->>Server: Request (ID: 123)
1499 | 61 | Note over Server: Processing starts
1500 | 62 | Client--)Server: notifications/cancelled (ID: 123)
1501 | 63 | alt
1502 | 64 | Note over Server: Processing may have<br/>completed before<br/>cancellation arrives
1503 | 65 | else If not completed
1504 | 66 | Note over Server: Stop processing
1505 | 67 | end
1506 | 68 | ```
1507 | 69 |
1508 | 70 | ## Implementation Notes
1509 | 71 |
1510 | 72 | - Both parties **SHOULD** log cancellation reasons for debugging
1511 | 73 | - Application UIs **SHOULD** indicate when cancellation is requested
1512 | 74 |
1513 | 75 | ## Error Handling
1514 | 76 |
1515 | 77 | Invalid cancellation notifications **SHOULD** be ignored:
1516 | 78 |
1517 | 79 | - Unknown request IDs
1518 | 80 | - Already completed requests
1519 | 81 | - Malformed notifications
1520 | 82 |
1521 | 83 | This maintains the "fire and forget" nature of notifications while allowing for race
1522 | 84 | conditions in asynchronous communication.
1523 | 85 |
1524 |
1525 |
1526 | --------------------------------------------------------------------------------
1527 | /docs/specification/2025-03-26/basic/utilities/ping.md:
1528 | --------------------------------------------------------------------------------
1529 | 1 | ---
1530 | 2 | title: Ping
1531 | 3 | weight: 5
1532 | 4 | ---
1533 | 5 |
1534 | 6 | {{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}}
1535 | 7 |
1536 | 8 | The Model Context Protocol includes an optional ping mechanism that allows either party
1537 | 9 | to verify that their counterpart is still responsive and the connection is alive.
1538 | 10 |
1539 | 11 | ## Overview
1540 | 12 |
1541 | 13 | The ping functionality is implemented through a simple request/response pattern. Either
1542 | 14 | the client or server can initiate a ping by sending a `ping` request.
1543 | 15 |
1544 | 16 | ## Message Format
1545 | 17 |
1546 | 18 | A ping request is a standard JSON-RPC request with no parameters:
1547 | 19 |
1548 | 20 | ```json
1549 | 21 | {
1550 | 22 | "jsonrpc": "2.0",
1551 | 23 | "id": "123",
1552 | 24 | "method": "ping"
1553 | 25 | }
1554 | 26 | ```
1555 | 27 |
1556 | 28 | ## Behavior Requirements
1557 | 29 |
1558 | 30 | 1. The receiver **MUST** respond promptly with an empty response:
1559 | 31 |
1560 | 32 | ```json
1561 | 33 | {
1562 | 34 | "jsonrpc": "2.0",
1563 | 35 | "id": "123",
1564 | 36 | "result": {}
1565 | 37 | }
1566 | 38 | ```
1567 | 39 |
1568 | 40 | 2. If no response is received within a reasonable timeout period, the sender **MAY**:
1569 | 41 | - Consider the connection stale
1570 | 42 | - Terminate the connection
1571 | 43 | - Attempt reconnection procedures
1572 | 44 |
1573 | 45 | ## Usage Patterns
1574 | 46 |
1575 | 47 | ```mermaid
1576 | 48 | sequenceDiagram
1577 | 49 | participant Sender
1578 | 50 | participant Receiver
1579 | 51 |
1580 | 52 | Sender->>Receiver: ping request
1581 | 53 | Receiver->>Sender: empty response
1582 | 54 | ```
1583 | 55 |
1584 | 56 | ## Implementation Considerations
1585 | 57 |
1586 | 58 | - Implementations **SHOULD** periodically issue pings to detect connection health
1587 | 59 | - The frequency of pings **SHOULD** be configurable
1588 | 60 | - Timeouts **SHOULD** be appropriate for the network environment
1589 | 61 | - Excessive pinging **SHOULD** be avoided to reduce network overhead
1590 | 62 |
1591 | 63 | ## Error Handling
1592 | 64 |
1593 | 65 | - Timeouts **SHOULD** be treated as connection failures
1594 | 66 | - Multiple failed pings **MAY** trigger connection reset
1595 | 67 | - Implementations **SHOULD** log ping failures for diagnostics
1596 | 68 |
1597 |
1598 |
1599 | --------------------------------------------------------------------------------
1600 | /docs/specification/2025-03-26/basic/utilities/progress.md:
1601 | --------------------------------------------------------------------------------
1602 | 1 | ---
1603 | 2 | title: Progress
1604 | 3 | weight: 30
1605 | 4 | ---
1606 | 5 |
1607 | 6 | {{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}}
1608 | 7 |
1609 | 8 | The Model Context Protocol (MCP) supports optional progress tracking for long-running
1610 | 9 | operations through notification messages. Either side can send progress notifications to
1611 | 10 | provide updates about operation status.
1612 | 11 |
1613 | 12 | ## Progress Flow
1614 | 13 |
1615 | 14 | When a party wants to _receive_ progress updates for a request, it includes a
1616 | 15 | `progressToken` in the request metadata.
1617 | 16 |
1618 | 17 | - Progress tokens **MUST** be a string or integer value
1619 | 18 | - Progress tokens can be chosen by the sender using any means, but **MUST** be unique
1620 | 19 | across all active requests.
1621 | 20 |
1622 | 21 | ```json
1623 | 22 | {
1624 | 23 | "jsonrpc": "2.0",
1625 | 24 | "id": 1,
1626 | 25 | "method": "some_method",
1627 | 26 | "params": {
1628 | 27 | "_meta": {
1629 | 28 | "progressToken": "abc123"
1630 | 29 | }
1631 | 30 | }
1632 | 31 | }
1633 | 32 | ```
1634 | 33 |
1635 | 34 | The receiver **MAY** then send progress notifications containing:
1636 | 35 |
1637 | 36 | - The original progress token
1638 | 37 | - The current progress value so far
1639 | 38 | - An optional "total" value
1640 | 39 | - An optional "message" value
1641 | 40 |
1642 | 41 | ```json
1643 | 42 | {
1644 | 43 | "jsonrpc": "2.0",
1645 | 44 | "method": "notifications/progress",
1646 | 45 | "params": {
1647 | 46 | "progressToken": "abc123",
1648 | 47 | "progress": 50,
1649 | 48 | "total": 100,
1650 | 49 | "message": "Reticulating splines..."
1651 | 50 | }
1652 | 51 | }
1653 | 52 | ```
1654 | 53 |
1655 | 54 | - The `progress` value **MUST** increase with each notification, even if the total is
1656 | 55 | unknown.
1657 | 56 | - The `progress` and the `total` values **MAY** be floating point.
1658 | 57 | - The `message` field **SHOULD** provide relevant human readable progress information.
1659 | 58 |
1660 | 59 | ## Behavior Requirements
1661 | 60 |
1662 | 61 | 1. Progress notifications **MUST** only reference tokens that:
1663 | 62 |
1664 | 63 | - Were provided in an active request
1665 | 64 | - Are associated with an in-progress operation
1666 | 65 |
1667 | 66 | 2. Receivers of progress requests **MAY**:
1668 | 67 | - Choose not to send any progress notifications
1669 | 68 | - Send notifications at whatever frequency they deem appropriate
1670 | 69 | - Omit the total value if unknown
1671 | 70 |
1672 | 71 | ```mermaid
1673 | 72 | sequenceDiagram
1674 | 73 | participant Sender
1675 | 74 | participant Receiver
1676 | 75 |
1677 | 76 | Note over Sender,Receiver: Request with progress token
1678 | 77 | Sender->>Receiver: Method request with progressToken
1679 | 78 |
1680 | 79 | Note over Sender,Receiver: Progress updates
1681 | 80 | loop Progress Updates
1682 | 81 | Receiver-->>Sender: Progress notification (0.2/1.0)
1683 | 82 | Receiver-->>Sender: Progress notification (0.6/1.0)
1684 | 83 | Receiver-->>Sender: Progress notification (1.0/1.0)
1685 | 84 | end
1686 | 85 |
1687 | 86 | Note over Sender,Receiver: Operation complete
1688 | 87 | Receiver->>Sender: Method response
1689 | 88 | ```
1690 | 89 |
1691 | 90 | ## Implementation Notes
1692 | 91 |
1693 | 92 | - Senders and receivers **SHOULD** track active progress tokens
1694 | 93 | - Both parties **SHOULD** implement rate limiting to prevent flooding
1695 | 94 | - Progress notifications **MUST** stop after completion
1696 | 95 |
1697 |
1698 |
1699 | --------------------------------------------------------------------------------
1700 | /docs/specification/2025-03-26/changelog.md:
1701 | --------------------------------------------------------------------------------
1702 | 1 | ---
1703 | 2 | title: Key Changes
1704 | 3 | type: docs
1705 | 4 | weight: 5
1706 | 5 | ---
1707 | 6 |
1708 | 7 | This document lists changes made to the Model Context Protocol (MCP) specification since
1709 | 8 | the previous revision, [2024-11-05]({{< ref "../2024-11-05" >}}).
1710 | 9 |
1711 | 10 | ## Major changes
1712 | 11 |
1713 | 12 | 1. Added a comprehensive **[authorization framework]({{< ref "basic/authorization" >}})**
1714 | 13 | based on OAuth 2.1 (PR
1715 | 14 | [#133](https://github.com/modelcontextprotocol/specification/pull/133))
1716 | 15 | 1. Replaced the previous HTTP+SSE transport with a more flexible **[Streamable HTTP
1717 | 16 | transport]({{< ref "basic/transports#streamable-http" >}})** (PR
1718 | 17 | [#206](https://github.com/modelcontextprotocol/specification/pull/206))
1719 | 18 | 1. Added support for JSON-RPC **[batching](https://www.jsonrpc.org/specification#batch)**
1720 | 19 | (PR [#228](https://github.com/modelcontextprotocol/specification/pull/228))
1721 | 20 | 1. Added comprehensive **tool annotations** for better describing tool behavior, like
1722 | 21 | whether it is read-only or destructive (PR
1723 | 22 | [#185](https://github.com/modelcontextprotocol/specification/pull/185))
1724 | 23 |
1725 | 24 | ## Other schema changes
1726 | 25 |
1727 | 26 | - Added `message` field to `ProgressNotification` to provide descriptive status updates
1728 | 27 | - Added support for audio data, joining the existing text and image content types
1729 | 28 | - Added `completions` capability to explicitly indicate support for argument
1730 | 29 | autocompletion suggestions
1731 | 30 |
1732 | 31 | See
1733 | 32 | [the updated schema](http://github.com/modelcontextprotocol/specification/tree/main/schema/2025-03-26/schema.ts)
1734 | 33 | for more details.
1735 | 34 |
1736 | 35 | ## Full changelog
1737 | 36 |
1738 | 37 | For a complete list of all changes that have been made since the last protocol revision,
1739 | 38 | [see GitHub](https://github.com/modelcontextprotocol/specification/compare/2024-11-05...2025-03-26).
1740 | 39 |
1741 |
1742 |
1743 | --------------------------------------------------------------------------------
1744 | /docs/specification/2025-03-26/client/_index.md:
1745 | --------------------------------------------------------------------------------
1746 | 1 | ---
1747 | 2 | title: Client Features
1748 | 3 | cascade:
1749 | 4 | type: docs
1750 | 5 | weight: 40
1751 | 6 | ---
1752 | 7 |
1753 | 8 | {{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}}
1754 | 9 |
1755 | 10 | Clients can implement additional features to enrich connected MCP servers:
1756 | 11 |
1757 | 12 | {{< cards >}} {{< card link="roots" title="Roots" icon="folder" >}}
1758 | 13 | {{< card link="sampling" title="Sampling" icon="annotation" >}} {{< /cards >}}
1759 | 14 |
1760 |
1761 |
1762 | --------------------------------------------------------------------------------
1763 | /docs/specification/2025-03-26/client/roots.md:
1764 | --------------------------------------------------------------------------------
1765 | 1 | ---
1766 | 2 | title: Roots
1767 | 3 | type: docs
1768 | 4 | weight: 40
1769 | 5 | ---
1770 | 6 |
1771 | 7 | {{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}}
1772 | 8 |
1773 | 9 | The Model Context Protocol (MCP) provides a standardized way for clients to expose
1774 | 10 | filesystem "roots" to servers. Roots define the boundaries of where servers can operate
1775 | 11 | within the filesystem, allowing them to understand which directories and files they have
1776 | 12 | access to. Servers can request the list of roots from supporting clients and receive
1777 | 13 | notifications when that list changes.
1778 | 14 |
1779 | 15 | ## User Interaction Model
1780 | 16 |
1781 | 17 | Roots in MCP are typically exposed through workspace or project configuration interfaces.
1782 | 18 |
1783 | 19 | For example, implementations could offer a workspace/project picker that allows users to
1784 | 20 | select directories and files the server should have access to. This can be combined with
1785 | 21 | automatic workspace detection from version control systems or project files.
1786 | 22 |
1787 | 23 | However, implementations are free to expose roots through any interface pattern that
1788 | 24 | suits their needs—the protocol itself does not mandate any specific user
1789 | 25 | interaction model.
1790 | 26 |
1791 | 27 | ## Capabilities
1792 | 28 |
1793 | 29 | Clients that support roots **MUST** declare the `roots` capability during
1794 | 30 | [initialization]({{< ref "../basic/lifecycle#initialization" >}}):
1795 | 31 |
1796 | 32 | ```json
1797 | 33 | {
1798 | 34 | "capabilities": {
1799 | 35 | "roots": {
1800 | 36 | "listChanged": true
1801 | 37 | }
1802 | 38 | }
1803 | 39 | }
1804 | 40 | ```
1805 | 41 |
1806 | 42 | `listChanged` indicates whether the client will emit notifications when the list of roots
1807 | 43 | changes.
1808 | 44 |
1809 | 45 | ## Protocol Messages
1810 | 46 |
1811 | 47 | ### Listing Roots
1812 | 48 |
1813 | 49 | To retrieve roots, servers send a `roots/list` request:
1814 | 50 |
1815 | 51 | **Request:**
1816 | 52 |
1817 | 53 | ```json
1818 | 54 | {
1819 | 55 | "jsonrpc": "2.0",
1820 | 56 | "id": 1,
1821 | 57 | "method": "roots/list"
1822 | 58 | }
1823 | 59 | ```
1824 | 60 |
1825 | 61 | **Response:**
1826 | 62 |
1827 | 63 | ```json
1828 | 64 | {
1829 | 65 | "jsonrpc": "2.0",
1830 | 66 | "id": 1,
1831 | 67 | "result": {
1832 | 68 | "roots": [
1833 | 69 | {
1834 | 70 | "uri": "file:///home/user/projects/myproject",
1835 | 71 | "name": "My Project"
1836 | 72 | }
1837 | 73 | ]
1838 | 74 | }
1839 | 75 | }
1840 | 76 | ```
1841 | 77 |
1842 | 78 | ### Root List Changes
1843 | 79 |
1844 | 80 | When roots change, clients that support `listChanged` **MUST** send a notification:
1845 | 81 |
1846 | 82 | ```json
1847 | 83 | {
1848 | 84 | "jsonrpc": "2.0",
1849 | 85 | "method": "notifications/roots/list_changed"
1850 | 86 | }
1851 | 87 | ```
1852 | 88 |
1853 | 89 | ## Message Flow
1854 | 90 |
1855 | 91 | ```mermaid
1856 | 92 | sequenceDiagram
1857 | 93 | participant Server
1858 | 94 | participant Client
1859 | 95 |
1860 | 96 | Note over Server,Client: Discovery
1861 | 97 | Server->>Client: roots/list
1862 | 98 | Client-->>Server: Available roots
1863 | 99 |
1864 | 100 | Note over Server,Client: Changes
1865 | 101 | Client--)Server: notifications/roots/list_changed
1866 | 102 | Server->>Client: roots/list
1867 | 103 | Client-->>Server: Updated roots
1868 | 104 | ```
1869 | 105 |
1870 | 106 | ## Data Types
1871 | 107 |
1872 | 108 | ### Root
1873 | 109 |
1874 | 110 | A root definition includes:
1875 | 111 |
1876 | 112 | - `uri`: Unique identifier for the root. This **MUST** be a `file://` URI in the current
1877 | 113 | specification.
1878 | 114 | - `name`: Optional human-readable name for display purposes.
1879 | 115 |
1880 | 116 | Example roots for different use cases:
1881 | 117 |
1882 | 118 | #### Project Directory
1883 | 119 |
1884 | 120 | ```json
1885 | 121 | {
1886 | 122 | "uri": "file:///home/user/projects/myproject",
1887 | 123 | "name": "My Project"
1888 | 124 | }
1889 | 125 | ```
1890 | 126 |
1891 | 127 | #### Multiple Repositories
1892 | 128 |
1893 | 129 | ```json
1894 | 130 | [
1895 | 131 | {
1896 | 132 | "uri": "file:///home/user/repos/frontend",
1897 | 133 | "name": "Frontend Repository"
1898 | 134 | },
1899 | 135 | {
1900 | 136 | "uri": "file:///home/user/repos/backend",
1901 | 137 | "name": "Backend Repository"
1902 | 138 | }
1903 | 139 | ]
1904 | 140 | ```
1905 | 141 |
1906 | 142 | ## Error Handling
1907 | 143 |
1908 | 144 | Clients **SHOULD** return standard JSON-RPC errors for common failure cases:
1909 | 145 |
1910 | 146 | - Client does not support roots: `-32601` (Method not found)
1911 | 147 | - Internal errors: `-32603`
1912 | 148 |
1913 | 149 | Example error:
1914 | 150 |
1915 | 151 | ```json
1916 | 152 | {
1917 | 153 | "jsonrpc": "2.0",
1918 | 154 | "id": 1,
1919 | 155 | "error": {
1920 | 156 | "code": -32601,
1921 | 157 | "message": "Roots not supported",
1922 | 158 | "data": {
1923 | 159 | "reason": "Client does not have roots capability"
1924 | 160 | }
1925 | 161 | }
1926 | 162 | }
1927 | 163 | ```
1928 | 164 |
1929 | 165 | ## Security Considerations
1930 | 166 |
1931 | 167 | 1. Clients **MUST**:
1932 | 168 |
1933 | 169 | - Only expose roots with appropriate permissions
1934 | 170 | - Validate all root URIs to prevent path traversal
1935 | 171 | - Implement proper access controls
1936 | 172 | - Monitor root accessibility
1937 | 173 |
1938 | 174 | 2. Servers **SHOULD**:
1939 | 175 | - Handle cases where roots become unavailable
1940 | 176 | - Respect root boundaries during operations
1941 | 177 | - Validate all paths against provided roots
1942 | 178 |
1943 | 179 | ## Implementation Guidelines
1944 | 180 |
1945 | 181 | 1. Clients **SHOULD**:
1946 | 182 |
1947 | 183 | - Prompt users for consent before exposing roots to servers
1948 | 184 | - Provide clear user interfaces for root management
1949 | 185 | - Validate root accessibility before exposing
1950 | 186 | - Monitor for root changes
1951 | 187 |
1952 | 188 | 2. Servers **SHOULD**:
1953 | 189 | - Check for roots capability before usage
1954 | 190 | - Handle root list changes gracefully
1955 | 191 | - Respect root boundaries in operations
1956 | 192 | - Cache root information appropriately
1957 | 193 |
1958 |
1959 |
1960 | --------------------------------------------------------------------------------
1961 | /docs/specification/2025-03-26/client/sampling.md:
1962 | --------------------------------------------------------------------------------
1963 | 1 | ---
1964 | 2 | title: Sampling
1965 | 3 | type: docs
1966 | 4 | weight: 40
1967 | 5 | ---
1968 | 6 |
1969 | 7 | {{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}}
1970 | 8 |
1971 | 9 | The Model Context Protocol (MCP) provides a standardized way for servers to request LLM
1972 | 10 | sampling ("completions" or "generations") from language models via clients. This flow
1973 | 11 | allows clients to maintain control over model access, selection, and permissions while
1974 | 12 | enabling servers to leverage AI capabilities—with no server API keys necessary.
1975 | 13 | Servers can request text, audio, or image-based interactions and optionally include
1976 | 14 | context from MCP servers in their prompts.
1977 | 15 |
1978 | 16 | ## User Interaction Model
1979 | 17 |
1980 | 18 | Sampling in MCP allows servers to implement agentic behaviors, by enabling LLM calls to
1981 | 19 | occur _nested_ inside other MCP server features.
1982 | 20 |
1983 | 21 | Implementations are free to expose sampling through any interface pattern that suits
1984 | 22 | their needs—the protocol itself does not mandate any specific user interaction
1985 | 23 | model.
1986 | 24 |
1987 | 25 | {{< callout type="warning" >}} For trust & safety and security, there **SHOULD** always
1988 | 26 | be a human in the loop with the ability to deny sampling requests.
1989 | 27 |
1990 | 28 | Applications **SHOULD**:
1991 | 29 |
1992 | 30 | - Provide UI that makes it easy and intuitive to review sampling requests
1993 | 31 | - Allow users to view and edit prompts before sending
1994 | 32 | - Present generated responses for review before delivery {{< /callout >}}
1995 | 33 |
1996 | 34 | ## Capabilities
1997 | 35 |
1998 | 36 | Clients that support sampling **MUST** declare the `sampling` capability during
1999 | 37 | [initialization]({{< ref "../basic/lifecycle#initialization" >}}):
2000 | 38 |
2001 | 39 | ```json
2002 | 40 | {
2003 | 41 | "capabilities": {
2004 | 42 | "sampling": {}
2005 | 43 | }
2006 | 44 | }
2007 | 45 | ```
2008 | 46 |
2009 | 47 | ## Protocol Messages
2010 | 48 |
2011 | 49 | ### Creating Messages
2012 | 50 |
2013 | 51 | To request a language model generation, servers send a `sampling/createMessage` request:
2014 | 52 |
2015 | 53 | **Request:**
2016 | 54 |
2017 | 55 | ```json
2018 | 56 | {
2019 | 57 | "jsonrpc": "2.0",
2020 | 58 | "id": 1,
2021 | 59 | "method": "sampling/createMessage",
2022 | 60 | "params": {
2023 | 61 | "messages": [
2024 | 62 | {
2025 | 63 | "role": "user",
2026 | 64 | "content": {
2027 | 65 | "type": "text",
2028 | 66 | "text": "What is the capital of France?"
2029 | 67 | }
2030 | 68 | }
2031 | 69 | ],
2032 | 70 | "modelPreferences": {
2033 | 71 | "hints": [
2034 | 72 | {
2035 | 73 | "name": "claude-3-sonnet"
2036 | 74 | }
2037 | 75 | ],
2038 | 76 | "intelligencePriority": 0.8,
2039 | 77 | "speedPriority": 0.5
2040 | 78 | },
2041 | 79 | "systemPrompt": "You are a helpful assistant.",
2042 | 80 | "maxTokens": 100
2043 | 81 | }
2044 | 82 | }
2045 | 83 | ```
2046 | 84 |
2047 | 85 | **Response:**
2048 | 86 |
2049 | 87 | ```json
2050 | 88 | {
2051 | 89 | "jsonrpc": "2.0",
2052 | 90 | "id": 1,
2053 | 91 | "result": {
2054 | 92 | "role": "assistant",
2055 | 93 | "content": {
2056 | 94 | "type": "text",
2057 | 95 | "text": "The capital of France is Paris."
2058 | 96 | },
2059 | 97 | "model": "claude-3-sonnet-20240307",
2060 | 98 | "stopReason": "endTurn"
2061 | 99 | }
2062 | 100 | }
2063 | 101 | ```
2064 | 102 |
2065 | 103 | ## Message Flow
2066 | 104 |
2067 | 105 | ```mermaid
2068 | 106 | sequenceDiagram
2069 | 107 | participant Server
2070 | 108 | participant Client
2071 | 109 | participant User
2072 | 110 | participant LLM
2073 | 111 |
2074 | 112 | Note over Server,Client: Server initiates sampling
2075 | 113 | Server->>Client: sampling/createMessage
2076 | 114 |
2077 | 115 | Note over Client,User: Human-in-the-loop review
2078 | 116 | Client->>User: Present request for approval
2079 | 117 | User-->>Client: Review and approve/modify
2080 | 118 |
2081 | 119 | Note over Client,LLM: Model interaction
2082 | 120 | Client->>LLM: Forward approved request
2083 | 121 | LLM-->>Client: Return generation
2084 | 122 |
2085 | 123 | Note over Client,User: Response review
2086 | 124 | Client->>User: Present response for approval
2087 | 125 | User-->>Client: Review and approve/modify
2088 | 126 |
2089 | 127 | Note over Server,Client: Complete request
2090 | 128 | Client-->>Server: Return approved response
2091 | 129 | ```
2092 | 130 |
2093 | 131 | ## Data Types
2094 | 132 |
2095 | 133 | ### Messages
2096 | 134 |
2097 | 135 | Sampling messages can contain:
2098 | 136 |
2099 | 137 | #### Text Content
2100 | 138 |
2101 | 139 | ```json
2102 | 140 | {
2103 | 141 | "type": "text",
2104 | 142 | "text": "The message content"
2105 | 143 | }
2106 | 144 | ```
2107 | 145 |
2108 | 146 | #### Image Content
2109 | 147 |
2110 | 148 | ```json
2111 | 149 | {
2112 | 150 | "type": "image",
2113 | 151 | "data": "base64-encoded-image-data",
2114 | 152 | "mimeType": "image/jpeg"
2115 | 153 | }
2116 | 154 | ```
2117 | 155 |
2118 | 156 | #### Audio Content
2119 | 157 |
2120 | 158 | ```json
2121 | 159 | {
2122 | 160 | "type": "audio",
2123 | 161 | "data": "base64-encoded-audio-data",
2124 | 162 | "mimeType": "audio/wav"
2125 | 163 | }
2126 | 164 | ```
2127 | 165 |
2128 | 166 | ### Model Preferences
2129 | 167 |
2130 | 168 | Model selection in MCP requires careful abstraction since servers and clients may use
2131 | 169 | different AI providers with distinct model offerings. A server cannot simply request a
2132 | 170 | specific model by name since the client may not have access to that exact model or may
2133 | 171 | prefer to use a different provider's equivalent model.
2134 | 172 |
2135 | 173 | To solve this, MCP implements a preference system that combines abstract capability
2136 | 174 | priorities with optional model hints:
2137 | 175 |
2138 | 176 | #### Capability Priorities
2139 | 177 |
2140 | 178 | Servers express their needs through three normalized priority values (0-1):
2141 | 179 |
2142 | 180 | - `costPriority`: How important is minimizing costs? Higher values prefer cheaper models.
2143 | 181 | - `speedPriority`: How important is low latency? Higher values prefer faster models.
2144 | 182 | - `intelligencePriority`: How important are advanced capabilities? Higher values prefer
2145 | 183 | more capable models.
2146 | 184 |
2147 | 185 | #### Model Hints
2148 | 186 |
2149 | 187 | While priorities help select models based on characteristics, `hints` allow servers to
2150 | 188 | suggest specific models or model families:
2151 | 189 |
2152 | 190 | - Hints are treated as substrings that can match model names flexibly
2153 | 191 | - Multiple hints are evaluated in order of preference
2154 | 192 | - Clients **MAY** map hints to equivalent models from different providers
2155 | 193 | - Hints are advisory—clients make final model selection
2156 | 194 |
2157 | 195 | For example:
2158 | 196 |
2159 | 197 | ```json
2160 | 198 | {
2161 | 199 | "hints": [
2162 | 200 | { "name": "claude-3-sonnet" }, // Prefer Sonnet-class models
2163 | 201 | { "name": "claude" } // Fall back to any Claude model
2164 | 202 | ],
2165 | 203 | "costPriority": 0.3, // Cost is less important
2166 | 204 | "speedPriority": 0.8, // Speed is very important
2167 | 205 | "intelligencePriority": 0.5 // Moderate capability needs
2168 | 206 | }
2169 | 207 | ```
2170 | 208 |
2171 | 209 | The client processes these preferences to select an appropriate model from its available
2172 | 210 | options. For instance, if the client doesn't have access to Claude models but has Gemini,
2173 | 211 | it might map the sonnet hint to `gemini-1.5-pro` based on similar capabilities.
2174 | 212 |
2175 | 213 | ## Error Handling
2176 | 214 |
2177 | 215 | Clients **SHOULD** return errors for common failure cases:
2178 | 216 |
2179 | 217 | Example error:
2180 | 218 |
2181 | 219 | ```json
2182 | 220 | {
2183 | 221 | "jsonrpc": "2.0",
2184 | 222 | "id": 1,
2185 | 223 | "error": {
2186 | 224 | "code": -1,
2187 | 225 | "message": "User rejected sampling request"
2188 | 226 | }
2189 | 227 | }
2190 | 228 | ```
2191 | 229 |
2192 | 230 | ## Security Considerations
2193 | 231 |
2194 | 232 | 1. Clients **SHOULD** implement user approval controls
2195 | 233 | 2. Both parties **SHOULD** validate message content
2196 | 234 | 3. Clients **SHOULD** respect model preference hints
2197 | 235 | 4. Clients **SHOULD** implement rate limiting
2198 | 236 | 5. Both parties **MUST** handle sensitive data appropriately
2199 | 237 |
2200 |
2201 |
2202 | --------------------------------------------------------------------------------
2203 | /docs/specification/2025-03-26/server/_index.md:
2204 | --------------------------------------------------------------------------------
2205 | 1 | ---
2206 | 2 | title: Server Features
2207 | 3 | cascade:
2208 | 4 | type: docs
2209 | 5 | weight: 30
2210 | 6 | ---
2211 | 7 |
2212 | 8 | {{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}}
2213 | 9 |
2214 | 10 | Servers provide the fundamental building blocks for adding context to language models via
2215 | 11 | MCP. These primitives enable rich interactions between clients, servers, and language
2216 | 12 | models:
2217 | 13 |
2218 | 14 | - **Prompts**: Pre-defined templates or instructions that guide language model
2219 | 15 | interactions
2220 | 16 | - **Resources**: Structured data or content that provides additional context to the model
2221 | 17 | - **Tools**: Executable functions that allow models to perform actions or retrieve
2222 | 18 | information
2223 | 19 |
2224 | 20 | Each primitive can be summarized in the following control hierarchy:
2225 | 21 |
2226 | 22 | | Primitive | Control | Description | Example |
2227 | 23 | | --------- | ---------------------- | -------------------------------------------------- | ------------------------------- |
2228 | 24 | | Prompts | User-controlled | Interactive templates invoked by user choice | Slash commands, menu options |
2229 | 25 | | Resources | Application-controlled | Contextual data attached and managed by the client | File contents, git history |
2230 | 26 | | Tools | Model-controlled | Functions exposed to the LLM to take actions | API POST requests, file writing |
2231 | 27 |
2232 | 28 | Explore these key primitives in more detail below:
2233 | 29 |
2234 | 30 | {{< cards >}} {{< card link="prompts" title="Prompts" icon="chat-alt-2" >}}
2235 | 31 | {{< card link="resources" title="Resources" icon="document" >}}
2236 | 32 | {{< card link="tools" title="Tools" icon="adjustments" >}} {{< /cards >}}
2237 | 33 |
2238 |
2239 |
2240 | --------------------------------------------------------------------------------
2241 | /docs/specification/2025-03-26/server/prompts.md:
2242 | --------------------------------------------------------------------------------
2243 | 1 | ---
2244 | 2 | title: Prompts
2245 | 3 | weight: 10
2246 | 4 | ---
2247 | 5 |
2248 | 6 | {{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}}
2249 | 7 |
2250 | 8 | The Model Context Protocol (MCP) provides a standardized way for servers to expose prompt
2251 | 9 | templates to clients. Prompts allow servers to provide structured messages and
2252 | 10 | instructions for interacting with language models. Clients can discover available
2253 | 11 | prompts, retrieve their contents, and provide arguments to customize them.
2254 | 12 |
2255 | 13 | ## User Interaction Model
2256 | 14 |
2257 | 15 | Prompts are designed to be **user-controlled**, meaning they are exposed from servers to
2258 | 16 | clients with the intention of the user being able to explicitly select them for use.
2259 | 17 |
2260 | 18 | Typically, prompts would be triggered through user-initiated commands in the user
2261 | 19 | interface, which allows users to naturally discover and invoke available prompts.
2262 | 20 |
2263 | 21 | For example, as slash commands:
2264 | 22 |
2265 | 23 | 
2266 | 24 |
2267 | 25 | However, implementors are free to expose prompts through any interface pattern that suits
2268 | 26 | their needs—the protocol itself does not mandate any specific user interaction
2269 | 27 | model.
2270 | 28 |
2271 | 29 | ## Capabilities
2272 | 30 |
2273 | 31 | Servers that support prompts **MUST** declare the `prompts` capability during
2274 | 32 | [initialization]({{< ref "../basic/lifecycle#initialization" >}}):
2275 | 33 |
2276 | 34 | /draft`json { "capabilities": { "prompts": { "listChanged": true } } }
2277 | 35 |
2278 | 36 | ````
2279 | 37 |
2280 | 38 | `listChanged` indicates whether the server will emit notifications when the list of
2281 | 39 | available prompts changes.
2282 | 40 |
2283 | 41 | ## Protocol Messages
2284 | 42 |
2285 | 43 | ### Listing Prompts
2286 | 44 |
2287 | 45 | To retrieve available prompts, clients send a `prompts/list` request. This operation
2288 | 46 | supports [pagination]({{< ref "utilities/pagination" >}}).
2289 | 47 |
2290 | 48 | **Request:**
2291 | 49 |
2292 | 50 | ```json
2293 | 51 | {
2294 | 52 | "jsonrpc": "2.0",
2295 | 53 | "id": 1,
2296 | 54 | "method": "prompts/list",
2297 | 55 | "params": {
2298 | 56 | "cursor": "optional-cursor-value"
2299 | 57 | }
2300 | 58 | }
2301 | 59 | ````
2302 | 60 |
2303 | 61 | **Response:**
2304 | 62 |
2305 | 63 | ```json
2306 | 64 | {
2307 | 65 | "jsonrpc": "2.0",
2308 | 66 | "id": 1,
2309 | 67 | "result": {
2310 | 68 | "prompts": [
2311 | 69 | {
2312 | 70 | "name": "code_review",
2313 | 71 | "description": "Asks the LLM to analyze code quality and suggest improvements",
2314 | 72 | "arguments": [
2315 | 73 | {
2316 | 74 | "name": "code",
2317 | 75 | "description": "The code to review",
2318 | 76 | "required": true
2319 | 77 | }
2320 | 78 | ]
2321 | 79 | }
2322 | 80 | ],
2323 | 81 | "nextCursor": "next-page-cursor"
2324 | 82 | }
2325 | 83 | }
2326 | 84 | ```
2327 | 85 |
2328 | 86 | ### Getting a Prompt
2329 | 87 |
2330 | 88 | To retrieve a specific prompt, clients send a `prompts/get` request. Arguments may be
2331 | 89 | auto-completed through [the completion API]({{< ref "utilities/completion" >}}).
2332 | 90 |
2333 | 91 | **Request:**
2334 | 92 |
2335 | 93 | ```json
2336 | 94 | {
2337 | 95 | "jsonrpc": "2.0",
2338 | 96 | "id": 2,
2339 | 97 | "method": "prompts/get",
2340 | 98 | "params": {
2341 | 99 | "name": "code_review",
2342 | 100 | "arguments": {
2343 | 101 | "code": "def hello():\n print('world')"
2344 | 102 | }
2345 | 103 | }
2346 | 104 | }
2347 | 105 | ```
2348 | 106 |
2349 | 107 | **Response:**
2350 | 108 |
2351 | 109 | ```json
2352 | 110 | {
2353 | 111 | "jsonrpc": "2.0",
2354 | 112 | "id": 2,
2355 | 113 | "result": {
2356 | 114 | "description": "Code review prompt",
2357 | 115 | "messages": [
2358 | 116 | {
2359 | 117 | "role": "user",
2360 | 118 | "content": {
2361 | 119 | "type": "text",
2362 | 120 | "text": "Please review this Python code:\ndef hello():\n print('world')"
2363 | 121 | }
2364 | 122 | }
2365 | 123 | ]
2366 | 124 | }
2367 | 125 | }
2368 | 126 | ```
2369 | 127 |
2370 | 128 | ### List Changed Notification
2371 | 129 |
2372 | 130 | When the list of available prompts changes, servers that declared the `listChanged`
2373 | 131 | capability **SHOULD** send a notification:
2374 | 132 |
2375 | 133 | ```json
2376 | 134 | {
2377 | 135 | "jsonrpc": "2.0",
2378 | 136 | "method": "notifications/prompts/list_changed"
2379 | 137 | }
2380 | 138 | ```
2381 | 139 |
2382 | 140 | ## Message Flow
2383 | 141 |
2384 | 142 | ```mermaid
2385 | 143 | sequenceDiagram
2386 | 144 | participant Client
2387 | 145 | participant Server
2388 | 146 |
2389 | 147 | Note over Client,Server: Discovery
2390 | 148 | Client->>Server: prompts/list
2391 | 149 | Server-->>Client: List of prompts
2392 | 150 |
2393 | 151 | Note over Client,Server: Usage
2394 | 152 | Client->>Server: prompts/get
2395 | 153 | Server-->>Client: Prompt content
2396 | 154 |
2397 | 155 | opt listChanged
2398 | 156 | Note over Client,Server: Changes
2399 | 157 | Server--)Client: prompts/list_changed
2400 | 158 | Client->>Server: prompts/list
2401 | 159 | Server-->>Client: Updated prompts
2402 | 160 | end
2403 | 161 | ```
2404 | 162 |
2405 | 163 | ## Data Types
2406 | 164 |
2407 | 165 | ### Prompt
2408 | 166 |
2409 | 167 | A prompt definition includes:
2410 | 168 |
2411 | 169 | - `name`: Unique identifier for the prompt
2412 | 170 | - `description`: Optional human-readable description
2413 | 171 | - `arguments`: Optional list of arguments for customization
2414 | 172 |
2415 | 173 | ### PromptMessage
2416 | 174 |
2417 | 175 | Messages in a prompt can contain:
2418 | 176 |
2419 | 177 | - `role`: Either "user" or "assistant" to indicate the speaker
2420 | 178 | - `content`: One of the following content types:
2421 | 179 |
2422 | 180 | #### Text Content
2423 | 181 |
2424 | 182 | Text content represents plain text messages:
2425 | 183 |
2426 | 184 | ```json
2427 | 185 | {
2428 | 186 | "type": "text",
2429 | 187 | "text": "The text content of the message"
2430 | 188 | }
2431 | 189 | ```
2432 | 190 |
2433 | 191 | This is the most common content type used for natural language interactions.
2434 | 192 |
2435 | 193 | #### Image Content
2436 | 194 |
2437 | 195 | Image content allows including visual information in messages:
2438 | 196 |
2439 | 197 | ```json
2440 | 198 | {
2441 | 199 | "type": "image",
2442 | 200 | "data": "base64-encoded-image-data",
2443 | 201 | "mimeType": "image/png"
2444 | 202 | }
2445 | 203 | ```
2446 | 204 |
2447 | 205 | The image data **MUST** be base64-encoded and include a valid MIME type. This enables
2448 | 206 | multi-modal interactions where visual context is important.
2449 | 207 |
2450 | 208 | #### Audio Content
2451 | 209 |
2452 | 210 | Audio content allows including audio information in messages:
2453 | 211 |
2454 | 212 | ```json
2455 | 213 | {
2456 | 214 | "type": "audio",
2457 | 215 | "data": "base64-encoded-audio-data",
2458 | 216 | "mimeType": "audio/wav"
2459 | 217 | }
2460 | 218 | ```
2461 | 219 |
2462 | 220 | The audio data MUST be base64-encoded and include a valid MIME type. This enables
2463 | 221 | multi-modal interactions where audio context is important.
2464 | 222 |
2465 | 223 | #### Embedded Resources
2466 | 224 |
2467 | 225 | Embedded resources allow referencing server-side resources directly in messages:
2468 | 226 |
2469 | 227 | ```json
2470 | 228 | {
2471 | 229 | "type": "resource",
2472 | 230 | "resource": {
2473 | 231 | "uri": "resource://example",
2474 | 232 | "mimeType": "text/plain",
2475 | 233 | "text": "Resource content"
2476 | 234 | }
2477 | 235 | }
2478 | 236 | ```
2479 | 237 |
2480 | 238 | Resources can contain either text or binary (blob) data and **MUST** include:
2481 | 239 |
2482 | 240 | - A valid resource URI
2483 | 241 | - The appropriate MIME type
2484 | 242 | - Either text content or base64-encoded blob data
2485 | 243 |
2486 | 244 | Embedded resources enable prompts to seamlessly incorporate server-managed content like
2487 | 245 | documentation, code samples, or other reference materials directly into the conversation
2488 | 246 | flow.
2489 | 247 |
2490 | 248 | ## Error Handling
2491 | 249 |
2492 | 250 | Servers **SHOULD** return standard JSON-RPC errors for common failure cases:
2493 | 251 |
2494 | 252 | - Invalid prompt name: `-32602` (Invalid params)
2495 | 253 | - Missing required arguments: `-32602` (Invalid params)
2496 | 254 | - Internal errors: `-32603` (Internal error)
2497 | 255 |
2498 | 256 | ## Implementation Considerations
2499 | 257 |
2500 | 258 | 1. Servers **SHOULD** validate prompt arguments before processing
2501 | 259 | 2. Clients **SHOULD** handle pagination for large prompt lists
2502 | 260 | 3. Both parties **SHOULD** respect capability negotiation
2503 | 261 |
2504 | 262 | ## Security
2505 | 263 |
2506 | 264 | Implementations **MUST** carefully validate all prompt inputs and outputs to prevent
2507 | 265 | injection attacks or unauthorized access to resources.
2508 | 266 |
2509 |
2510 |
2511 | --------------------------------------------------------------------------------
2512 | /docs/specification/2025-03-26/server/resource-picker.png:
2513 | --------------------------------------------------------------------------------
2514 | https://raw.githubusercontent.com/modelcontextprotocol/specification/main/docs/specification/2025-03-26/server/resource-picker.png
2515 |
2516 |
2517 | --------------------------------------------------------------------------------
2518 | /docs/specification/2025-03-26/server/resources.md:
2519 | --------------------------------------------------------------------------------
2520 | 1 | ---
2521 | 2 | title: Resources
2522 | 3 | type: docs
2523 | 4 | weight: 20
2524 | 5 | ---
2525 | 6 |
2526 | 7 | {{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}}
2527 | 8 |
2528 | 9 | The Model Context Protocol (MCP) provides a standardized way for servers to expose
2529 | 10 | resources to clients. Resources allow servers to share data that provides context to
2530 | 11 | language models, such as files, database schemas, or application-specific information.
2531 | 12 | Each resource is uniquely identified by a
2532 | 13 | [URI](https://datatracker.ietf.org/doc/html/rfc3986).
2533 | 14 |
2534 | 15 | ## User Interaction Model
2535 | 16 |
2536 | 17 | Resources in MCP are designed to be **application-driven**, with host applications
2537 | 18 | determining how to incorporate context based on their needs.
2538 | 19 |
2539 | 20 | For example, applications could:
2540 | 21 |
2541 | 22 | - Expose resources through UI elements for explicit selection, in a tree or list view
2542 | 23 | - Allow the user to search through and filter available resources
2543 | 24 | - Implement automatic context inclusion, based on heuristics or the AI model's selection
2544 | 25 |
2545 | 26 | 
2546 | 27 |
2547 | 28 | However, implementations are free to expose resources through any interface pattern that
2548 | 29 | suits their needs—the protocol itself does not mandate any specific user
2549 | 30 | interaction model.
2550 | 31 |
2551 | 32 | ## Capabilities
2552 | 33 |
2553 | 34 | Servers that support resources **MUST** declare the `resources` capability:
2554 | 35 |
2555 | 36 | ```json
2556 | 37 | {
2557 | 38 | "capabilities": {
2558 | 39 | "resources": {
2559 | 40 | "subscribe": true,
2560 | 41 | "listChanged": true
2561 | 42 | }
2562 | 43 | }
2563 | 44 | }
2564 | 45 | ```
2565 | 46 |
2566 | 47 | The capability supports two optional features:
2567 | 48 |
2568 | 49 | - `subscribe`: whether the client can subscribe to be notified of changes to individual
2569 | 50 | resources.
2570 | 51 | - `listChanged`: whether the server will emit notifications when the list of available
2571 | 52 | resources changes.
2572 | 53 |
2573 | 54 | Both `subscribe` and `listChanged` are optional—servers can support neither,
2574 | 55 | either, or both:
2575 | 56 |
2576 | 57 | ```json
2577 | 58 | {
2578 | 59 | "capabilities": {
2579 | 60 | "resources": {} // Neither feature supported
2580 | 61 | }
2581 | 62 | }
2582 | 63 | ```
2583 | 64 |
2584 | 65 | ```json
2585 | 66 | {
2586 | 67 | "capabilities": {
2587 | 68 | "resources": {
2588 | 69 | "subscribe": true // Only subscriptions supported
2589 | 70 | }
2590 | 71 | }
2591 | 72 | }
2592 | 73 | ```
2593 | 74 |
2594 | 75 | ```json
2595 | 76 | {
2596 | 77 | "capabilities": {
2597 | 78 | "resources": {
2598 | 79 | "listChanged": true // Only list change notifications supported
2599 | 80 | }
2600 | 81 | }
2601 | 82 | }
2602 | 83 | ```
2603 | 84 |
2604 | 85 | ## Protocol Messages
2605 | 86 |
2606 | 87 | ### Listing Resources
2607 | 88 |
2608 | 89 | To discover available resources, clients send a `resources/list` request. This operation
2609 | 90 | supports [pagination]({{< ref "utilities/pagination" >}}).
2610 | 91 |
2611 | 92 | **Request:**
2612 | 93 |
2613 | 94 | ```json
2614 | 95 | {
2615 | 96 | "jsonrpc": "2.0",
2616 | 97 | "id": 1,
2617 | 98 | "method": "resources/list",
2618 | 99 | "params": {
2619 | 100 | "cursor": "optional-cursor-value"
2620 | 101 | }
2621 | 102 | }
2622 | 103 | ```
2623 | 104 |
2624 | 105 | **Response:**
2625 | 106 |
2626 | 107 | ```json
2627 | 108 | {
2628 | 109 | "jsonrpc": "2.0",
2629 | 110 | "id": 1,
2630 | 111 | "result": {
2631 | 112 | "resources": [
2632 | 113 | {
2633 | 114 | "uri": "file:///project/src/main.rs",
2634 | 115 | "name": "main.rs",
2635 | 116 | "description": "Primary application entry point",
2636 | 117 | "mimeType": "text/x-rust"
2637 | 118 | }
2638 | 119 | ],
2639 | 120 | "nextCursor": "next-page-cursor"
2640 | 121 | }
2641 | 122 | }
2642 | 123 | ```
2643 | 124 |
2644 | 125 | ### Reading Resources
2645 | 126 |
2646 | 127 | To retrieve resource contents, clients send a `resources/read` request:
2647 | 128 |
2648 | 129 | **Request:**
2649 | 130 |
2650 | 131 | ```json
2651 | 132 | {
2652 | 133 | "jsonrpc": "2.0",
2653 | 134 | "id": 2,
2654 | 135 | "method": "resources/read",
2655 | 136 | "params": {
2656 | 137 | "uri": "file:///project/src/main.rs"
2657 | 138 | }
2658 | 139 | }
2659 | 140 | ```
2660 | 141 |
2661 | 142 | **Response:**
2662 | 143 |
2663 | 144 | ```json
2664 | 145 | {
2665 | 146 | "jsonrpc": "2.0",
2666 | 147 | "id": 2,
2667 | 148 | "result": {
2668 | 149 | "contents": [
2669 | 150 | {
2670 | 151 | "uri": "file:///project/src/main.rs",
2671 | 152 | "mimeType": "text/x-rust",
2672 | 153 | "text": "fn main() {\n println!(\"Hello world!\");\n}"
2673 | 154 | }
2674 | 155 | ]
2675 | 156 | }
2676 | 157 | }
2677 | 158 | ```
2678 | 159 |
2679 | 160 | ### Resource Templates
2680 | 161 |
2681 | 162 | Resource templates allow servers to expose parameterized resources using
2682 | 163 | [URI templates](https://datatracker.ietf.org/doc/html/rfc6570). Arguments may be
2683 | 164 | auto-completed through [the completion API]({{< ref "utilities/completion" >}}).
2684 | 165 |
2685 | 166 | **Request:**
2686 | 167 |
2687 | 168 | ```json
2688 | 169 | {
2689 | 170 | "jsonrpc": "2.0",
2690 | 171 | "id": 3,
2691 | 172 | "method": "resources/templates/list"
2692 | 173 | }
2693 | 174 | ```
2694 | 175 |
2695 | 176 | **Response:**
2696 | 177 |
2697 | 178 | ```json
2698 | 179 | {
2699 | 180 | "jsonrpc": "2.0",
2700 | 181 | "id": 3,
2701 | 182 | "result": {
2702 | 183 | "resourceTemplates": [
2703 | 184 | {
2704 | 185 | "uriTemplate": "file:///{path}",
2705 | 186 | "name": "Project Files",
2706 | 187 | "description": "Access files in the project directory",
2707 | 188 | "mimeType": "application/octet-stream"
2708 | 189 | }
2709 | 190 | ]
2710 | 191 | }
2711 | 192 | }
2712 | 193 | ```
2713 | 194 |
2714 | 195 | ### List Changed Notification
2715 | 196 |
2716 | 197 | When the list of available resources changes, servers that declared the `listChanged`
2717 | 198 | capability **SHOULD** send a notification:
2718 | 199 |
2719 | 200 | ```json
2720 | 201 | {
2721 | 202 | "jsonrpc": "2.0",
2722 | 203 | "method": "notifications/resources/list_changed"
2723 | 204 | }
2724 | 205 | ```
2725 | 206 |
2726 | 207 | ### Subscriptions
2727 | 208 |
2728 | 209 | The protocol supports optional subscriptions to resource changes. Clients can subscribe
2729 | 210 | to specific resources and receive notifications when they change:
2730 | 211 |
2731 | 212 | **Subscribe Request:**
2732 | 213 |
2733 | 214 | ```json
2734 | 215 | {
2735 | 216 | "jsonrpc": "2.0",
2736 | 217 | "id": 4,
2737 | 218 | "method": "resources/subscribe",
2738 | 219 | "params": {
2739 | 220 | "uri": "file:///project/src/main.rs"
2740 | 221 | }
2741 | 222 | }
2742 | 223 | ```
2743 | 224 |
2744 | 225 | **Update Notification:**
2745 | 226 |
2746 | 227 | ```json
2747 | 228 | {
2748 | 229 | "jsonrpc": "2.0",
2749 | 230 | "method": "notifications/resources/updated",
2750 | 231 | "params": {
2751 | 232 | "uri": "file:///project/src/main.rs"
2752 | 233 | }
2753 | 234 | }
2754 | 235 | ```
2755 | 236 |
2756 | 237 | ## Message Flow
2757 | 238 |
2758 | 239 | ```mermaid
2759 | 240 | sequenceDiagram
2760 | 241 | participant Client
2761 | 242 | participant Server
2762 | 243 |
2763 | 244 | Note over Client,Server: Resource Discovery
2764 | 245 | Client->>Server: resources/list
2765 | 246 | Server-->>Client: List of resources
2766 | 247 |
2767 | 248 | Note over Client,Server: Resource Access
2768 | 249 | Client->>Server: resources/read
2769 | 250 | Server-->>Client: Resource contents
2770 | 251 |
2771 | 252 | Note over Client,Server: Subscriptions
2772 | 253 | Client->>Server: resources/subscribe
2773 | 254 | Server-->>Client: Subscription confirmed
2774 | 255 |
2775 | 256 | Note over Client,Server: Updates
2776 | 257 | Server--)Client: notifications/resources/updated
2777 | 258 | Client->>Server: resources/read
2778 | 259 | Server-->>Client: Updated contents
2779 | 260 | ```
2780 | 261 |
2781 | 262 | ## Data Types
2782 | 263 |
2783 | 264 | ### Resource
2784 | 265 |
2785 | 266 | A resource definition includes:
2786 | 267 |
2787 | 268 | - `uri`: Unique identifier for the resource
2788 | 269 | - `name`: Human-readable name
2789 | 270 | - `description`: Optional description
2790 | 271 | - `mimeType`: Optional MIME type
2791 | 272 | - `size`: Optional size in bytes
2792 | 273 |
2793 | 274 | ### Resource Contents
2794 | 275 |
2795 | 276 | Resources can contain either text or binary data:
2796 | 277 |
2797 | 278 | #### Text Content
2798 | 279 |
2799 | 280 | ```json
2800 | 281 | {
2801 | 282 | "uri": "file:///example.txt",
2802 | 283 | "mimeType": "text/plain",
2803 | 284 | "text": "Resource content"
2804 | 285 | }
2805 | 286 | ```
2806 | 287 |
2807 | 288 | #### Binary Content
2808 | 289 |
2809 | 290 | ```json
2810 | 291 | {
2811 | 292 | "uri": "file:///example.png",
2812 | 293 | "mimeType": "image/png",
2813 | 294 | "blob": "base64-encoded-data"
2814 | 295 | }
2815 | 296 | ```
2816 | 297 |
2817 | 298 | ## Common URI Schemes
2818 | 299 |
2819 | 300 | The protocol defines several standard URI schemes. This list not
2820 | 301 | exhaustive—implementations are always free to use additional, custom URI schemes.
2821 | 302 |
2822 | 303 | ### https://
2823 | 304 |
2824 | 305 | Used to represent a resource available on the web.
2825 | 306 |
2826 | 307 | Servers **SHOULD** use this scheme only when the client is able to fetch and load the
2827 | 308 | resource directly from the web on its own—that is, it doesn’t need to read the resource
2828 | 309 | via the MCP server.
2829 | 310 |
2830 | 311 | For other use cases, servers **SHOULD** prefer to use another URI scheme, or define a
2831 | 312 | custom one, even if the server will itself be downloading resource contents over the
2832 | 313 | internet.
2833 | 314 |
2834 | 315 | ### file://
2835 | 316 |
2836 | 317 | Used to identify resources that behave like a filesystem. However, the resources do not
2837 | 318 | need to map to an actual physical filesystem.
2838 | 319 |
2839 | 320 | MCP servers **MAY** identify file:// resources with an
2840 | 321 | [XDG MIME type](https://specifications.freedesktop.org/shared-mime-info-spec/0.14/ar01s02.html#id-1.3.14),
2841 | 322 | like `inode/directory`, to represent non-regular files (such as directories) that don’t
2842 | 323 | otherwise have a standard MIME type.
2843 | 324 |
2844 | 325 | ### git://
2845 | 326 |
2846 | 327 | Git version control integration.
2847 | 328 |
2848 | 329 | ## Error Handling
2849 | 330 |
2850 | 331 | Servers **SHOULD** return standard JSON-RPC errors for common failure cases:
2851 | 332 |
2852 | 333 | - Resource not found: `-32002`
2853 | 334 | - Internal errors: `-32603`
2854 | 335 |
2855 | 336 | Example error:
2856 | 337 |
2857 | 338 | ```json
2858 | 339 | {
2859 | 340 | "jsonrpc": "2.0",
2860 | 341 | "id": 5,
2861 | 342 | "error": {
2862 | 343 | "code": -32002,
2863 | 344 | "message": "Resource not found",
2864 | 345 | "data": {
2865 | 346 | "uri": "file:///nonexistent.txt"
2866 | 347 | }
2867 | 348 | }
2868 | 349 | }
2869 | 350 | ```
2870 | 351 |
2871 | 352 | ## Security Considerations
2872 | 353 |
2873 | 354 | 1. Servers **MUST** validate all resource URIs
2874 | 355 | 2. Access controls **SHOULD** be implemented for sensitive resources
2875 | 356 | 3. Binary data **MUST** be properly encoded
2876 | 357 | 4. Resource permissions **SHOULD** be checked before operations
2877 | 358 |
2878 |
2879 |
2880 | --------------------------------------------------------------------------------
2881 | /docs/specification/2025-03-26/server/slash-command.png:
2882 | --------------------------------------------------------------------------------
2883 | https://raw.githubusercontent.com/modelcontextprotocol/specification/main/docs/specification/2025-03-26/server/slash-command.png
2884 |
2885 |
2886 | --------------------------------------------------------------------------------
2887 | /docs/specification/2025-03-26/server/tools.md:
2888 | --------------------------------------------------------------------------------
2889 | 1 | ---
2890 | 2 | title: Tools
2891 | 3 | type: docs
2892 | 4 | weight: 40
2893 | 5 | ---
2894 | 6 |
2895 | 7 | {{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}}
2896 | 8 |
2897 | 9 | The Model Context Protocol (MCP) allows servers to expose tools that can be invoked by
2898 | 10 | language models. Tools enable models to interact with external systems, such as querying
2899 | 11 | databases, calling APIs, or performing computations. Each tool is uniquely identified by
2900 | 12 | a name and includes metadata describing its schema.
2901 | 13 |
2902 | 14 | ## User Interaction Model
2903 | 15 |
2904 | 16 | Tools in MCP are designed to be **model-controlled**, meaning that the language model can
2905 | 17 | discover and invoke tools automatically based on its contextual understanding and the
2906 | 18 | user's prompts.
2907 | 19 |
2908 | 20 | However, implementations are free to expose tools through any interface pattern that
2909 | 21 | suits their needs—the protocol itself does not mandate any specific user
2910 | 22 | interaction model.
2911 | 23 |
2912 | 24 | {{< callout type="warning" >}} For trust & safety and security, there **SHOULD** always
2913 | 25 | be a human in the loop with the ability to deny tool invocations.
2914 | 26 |
2915 | 27 | Applications **SHOULD**:
2916 | 28 |
2917 | 29 | - Provide UI that makes clear which tools are being exposed to the AI model
2918 | 30 | - Insert clear visual indicators when tools are invoked
2919 | 31 | - Present confirmation prompts to the user for operations, to ensure a human is in the
2920 | 32 | loop {{< /callout >}}
2921 | 33 |
2922 | 34 | ## Capabilities
2923 | 35 |
2924 | 36 | Servers that support tools **MUST** declare the `tools` capability:
2925 | 37 |
2926 | 38 | ```json
2927 | 39 | {
2928 | 40 | "capabilities": {
2929 | 41 | "tools": {
2930 | 42 | "listChanged": true
2931 | 43 | }
2932 | 44 | }
2933 | 45 | }
2934 | 46 | ```
2935 | 47 |
2936 | 48 | `listChanged` indicates whether the server will emit notifications when the list of
2937 | 49 | available tools changes.
2938 | 50 |
2939 | 51 | ## Protocol Messages
2940 | 52 |
2941 | 53 | ### Listing Tools
2942 | 54 |
2943 | 55 | To discover available tools, clients send a `tools/list` request. This operation supports
2944 | 56 | [pagination]({{< ref "utilities/pagination" >}}).
2945 | 57 |
2946 | 58 | **Request:**
2947 | 59 |
2948 | 60 | ```json
2949 | 61 | {
2950 | 62 | "jsonrpc": "2.0",
2951 | 63 | "id": 1,
2952 | 64 | "method": "tools/list",
2953 | 65 | "params": {
2954 | 66 | "cursor": "optional-cursor-value"
2955 | 67 | }
2956 | 68 | }
2957 | 69 | ```
2958 | 70 |
2959 | 71 | **Response:**
2960 | 72 |
2961 | 73 | ```json
2962 | 74 | {
2963 | 75 | "jsonrpc": "2.0",
2964 | 76 | "id": 1,
2965 | 77 | "result": {
2966 | 78 | "tools": [
2967 | 79 | {
2968 | 80 | "name": "get_weather",
2969 | 81 | "description": "Get current weather information for a location",
2970 | 82 | "inputSchema": {
2971 | 83 | "type": "object",
2972 | 84 | "properties": {
2973 | 85 | "location": {
2974 | 86 | "type": "string",
2975 | 87 | "description": "City name or zip code"
2976 | 88 | }
2977 | 89 | },
2978 | 90 | "required": ["location"]
2979 | 91 | }
2980 | 92 | }
2981 | 93 | ],
2982 | 94 | "nextCursor": "next-page-cursor"
2983 | 95 | }
2984 | 96 | }
2985 | 97 | ```
2986 | 98 |
2987 | 99 | ### Calling Tools
2988 | 100 |
2989 | 101 | To invoke a tool, clients send a `tools/call` request:
2990 | 102 |
2991 | 103 | **Request:**
2992 | 104 |
2993 | 105 | ```json
2994 | 106 | {
2995 | 107 | "jsonrpc": "2.0",
2996 | 108 | "id": 2,
2997 | 109 | "method": "tools/call",
2998 | 110 | "params": {
2999 | 111 | "name": "get_weather",
3000 | 112 | "arguments": {
3001 | 113 | "location": "New York"
3002 | 114 | }
3003 | 115 | }
3004 | 116 | }
3005 | 117 | ```
3006 | 118 |
3007 | 119 | **Response:**
3008 | 120 |
3009 | 121 | ```json
3010 | 122 | {
3011 | 123 | "jsonrpc": "2.0",
3012 | 124 | "id": 2,
3013 | 125 | "result": {
3014 | 126 | "content": [
3015 | 127 | {
3016 | 128 | "type": "text",
3017 | 129 | "text": "Current weather in New York:\nTemperature: 72°F\nConditions: Partly cloudy"
3018 | 130 | }
3019 | 131 | ],
3020 | 132 | "isError": false
3021 | 133 | }
3022 | 134 | }
3023 | 135 | ```
3024 | 136 |
3025 | 137 | ### List Changed Notification
3026 | 138 |
3027 | 139 | When the list of available tools changes, servers that declared the `listChanged`
3028 | 140 | capability **SHOULD** send a notification:
3029 | 141 |
3030 | 142 | ```json
3031 | 143 | {
3032 | 144 | "jsonrpc": "2.0",
3033 | 145 | "method": "notifications/tools/list_changed"
3034 | 146 | }
3035 | 147 | ```
3036 | 148 |
3037 | 149 | ## Message Flow
3038 | 150 |
3039 | 151 | ```mermaid
3040 | 152 | sequenceDiagram
3041 | 153 | participant LLM
3042 | 154 | participant Client
3043 | 155 | participant Server
3044 | 156 |
3045 | 157 | Note over Client,Server: Discovery
3046 | 158 | Client->>Server: tools/list
3047 | 159 | Server-->>Client: List of tools
3048 | 160 |
3049 | 161 | Note over Client,LLM: Tool Selection
3050 | 162 | LLM->>Client: Select tool to use
3051 | 163 |
3052 | 164 | Note over Client,Server: Invocation
3053 | 165 | Client->>Server: tools/call
3054 | 166 | Server-->>Client: Tool result
3055 | 167 | Client->>LLM: Process result
3056 | 168 |
3057 | 169 | Note over Client,Server: Updates
3058 | 170 | Server--)Client: tools/list_changed
3059 | 171 | Client->>Server: tools/list
3060 | 172 | Server-->>Client: Updated tools
3061 | 173 | ```
3062 | 174 |
3063 | 175 | ## Data Types
3064 | 176 |
3065 | 177 | ### Tool
3066 | 178 |
3067 | 179 | A tool definition includes:
3068 | 180 |
3069 | 181 | - `name`: Unique identifier for the tool
3070 | 182 | - `description`: Human-readable description of functionality
3071 | 183 | - `inputSchema`: JSON Schema defining expected parameters
3072 | 184 | - `annotations`: optional properties describing tool behavior
3073 | 185 |
3074 | 186 | {{< callout type="warning" >}} For trust & safety and security, clients **MUST** consider
3075 | 187 | tool annotations to be untrusted unless they come from trusted servers. {{< /callout >}}
3076 | 188 |
3077 | 189 | ### Tool Result
3078 | 190 |
3079 | 191 | Tool results can contain multiple content items of different types:
3080 | 192 |
3081 | 193 | #### Text Content
3082 | 194 |
3083 | 195 | ```json
3084 | 196 | {
3085 | 197 | "type": "text",
3086 | 198 | "text": "Tool result text"
3087 | 199 | }
3088 | 200 | ```
3089 | 201 |
3090 | 202 | #### Image Content
3091 | 203 |
3092 | 204 | ```json
3093 | 205 | {
3094 | 206 | "type": "image",
3095 | 207 | "data": "base64-encoded-data",
3096 | 208 | "mimeType": "image/png"
3097 | 209 | }
3098 | 210 | ```
3099 | 211 |
3100 | 212 | #### Audio Content
3101 | 213 |
3102 | 214 | ```json
3103 | 215 | {
3104 | 216 | "type": "audio",
3105 | 217 | "data": "base64-encoded-audio-data",
3106 | 218 | "mimeType": "audio/wav"
3107 | 219 | }
3108 | 220 | ```
3109 | 221 |
3110 | 222 | #### Embedded Resources
3111 | 223 |
3112 | 224 | [Resources]({{< ref "resources" >}}) **MAY** be embedded, to provide additional context
3113 | 225 | or data, behind a URI that can be subscribed to or fetched again by the client later:
3114 | 226 |
3115 | 227 | ```json
3116 | 228 | {
3117 | 229 | "type": "resource",
3118 | 230 | "resource": {
3119 | 231 | "uri": "resource://example",
3120 | 232 | "mimeType": "text/plain",
3121 | 233 | "text": "Resource content"
3122 | 234 | }
3123 | 235 | }
3124 | 236 | ```
3125 | 237 |
3126 | 238 | ## Error Handling
3127 | 239 |
3128 | 240 | Tools use two error reporting mechanisms:
3129 | 241 |
3130 | 242 | 1. **Protocol Errors**: Standard JSON-RPC errors for issues like:
3131 | 243 |
3132 | 244 | - Unknown tools
3133 | 245 | - Invalid arguments
3134 | 246 | - Server errors
3135 | 247 |
3136 | 248 | 2. **Tool Execution Errors**: Reported in tool results with `isError: true`:
3137 | 249 | - API failures
3138 | 250 | - Invalid input data
3139 | 251 | - Business logic errors
3140 | 252 |
3141 | 253 | Example protocol error:
3142 | 254 |
3143 | 255 | ```json
3144 | 256 | {
3145 | 257 | "jsonrpc": "2.0",
3146 | 258 | "id": 3,
3147 | 259 | "error": {
3148 | 260 | "code": -32602,
3149 | 261 | "message": "Unknown tool: invalid_tool_name"
3150 | 262 | }
3151 | 263 | }
3152 | 264 | ```
3153 | 265 |
3154 | 266 | Example tool execution error:
3155 | 267 |
3156 | 268 | ```json
3157 | 269 | {
3158 | 270 | "jsonrpc": "2.0",
3159 | 271 | "id": 4,
3160 | 272 | "result": {
3161 | 273 | "content": [
3162 | 274 | {
3163 | 275 | "type": "text",
3164 | 276 | "text": "Failed to fetch weather data: API rate limit exceeded"
3165 | 277 | }
3166 | 278 | ],
3167 | 279 | "isError": true
3168 | 280 | }
3169 | 281 | }
3170 | 282 | ```
3171 | 283 |
3172 | 284 | ## Security Considerations
3173 | 285 |
3174 | 286 | 1. Servers **MUST**:
3175 | 287 |
3176 | 288 | - Validate all tool inputs
3177 | 289 | - Implement proper access controls
3178 | 290 | - Rate limit tool invocations
3179 | 291 | - Sanitize tool outputs
3180 | 292 |
3181 | 293 | 2. Clients **SHOULD**:
3182 | 294 | - Prompt for user confirmation on sensitive operations
3183 | 295 | - Show tool inputs to the user before calling the server, to avoid malicious or
3184 | 296 | accidental data exfiltration
3185 | 297 | - Validate tool results before passing to LLM
3186 | 298 | - Implement timeouts for tool calls
3187 | 299 | - Log tool usage for audit purposes
3188 | 300 |
3189 |
3190 |
3191 | --------------------------------------------------------------------------------
3192 | /docs/specification/2025-03-26/server/utilities/_index.md:
3193 | --------------------------------------------------------------------------------
3194 | 1 | ---
3195 | 2 | title: Utilities
3196 | 3 | ---
3197 | 4 |
3198 | 5 | {{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}}
3199 | 6 |
3200 | 7 | These optional features can be used to enhance server functionality.
3201 | 8 |
3202 | 9 | {{< cards >}} {{< card link="completion" title="Completion" icon="at-symbol" >}}
3203 | 10 | {{< card link="logging" title="Logging" icon="terminal" >}}
3204 | 11 | {{< card link="pagination" title="Pagination" icon="collection" >}} {{< /cards >}}
3205 | 12 |
3206 |
3207 |
3208 | --------------------------------------------------------------------------------
3209 | /docs/specification/2025-03-26/server/utilities/completion.md:
3210 | --------------------------------------------------------------------------------
3211 | 1 | ---
3212 | 2 | title: Completion
3213 | 3 | ---
3214 | 4 |
3215 | 5 | {{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}}
3216 | 6 |
3217 | 7 | The Model Context Protocol (MCP) provides a standardized way for servers to offer
3218 | 8 | argument autocompletion suggestions for prompts and resource URIs. This enables rich,
3219 | 9 | IDE-like experiences where users receive contextual suggestions while entering argument
3220 | 10 | values.
3221 | 11 |
3222 | 12 | ## User Interaction Model
3223 | 13 |
3224 | 14 | Completion in MCP is designed to support interactive user experiences similar to IDE code
3225 | 15 | completion.
3226 | 16 |
3227 | 17 | For example, applications may show completion suggestions in a dropdown or popup menu as
3228 | 18 | users type, with the ability to filter and select from available options.
3229 | 19 |
3230 | 20 | However, implementations are free to expose completion through any interface pattern that
3231 | 21 | suits their needs—the protocol itself does not mandate any specific user
3232 | 22 | interaction model.
3233 | 23 |
3234 | 24 | ## Capabilities
3235 | 25 |
3236 | 26 | Servers that support completions **MUST** declare the `completions` capability:
3237 | 27 |
3238 | 28 | ```json
3239 | 29 | {
3240 | 30 | "capabilities": {
3241 | 31 | "completions": {}
3242 | 32 | }
3243 | 33 | }
3244 | 34 | ```
3245 | 35 |
3246 | 36 | ## Protocol Messages
3247 | 37 |
3248 | 38 | ### Requesting Completions
3249 | 39 |
3250 | 40 | To get completion suggestions, clients send a `completion/complete` request specifying
3251 | 41 | what is being completed through a reference type:
3252 | 42 |
3253 | 43 | **Request:**
3254 | 44 |
3255 | 45 | ```json
3256 | 46 | {
3257 | 47 | "jsonrpc": "2.0",
3258 | 48 | "id": 1,
3259 | 49 | "method": "completion/complete",
3260 | 50 | "params": {
3261 | 51 | "ref": {
3262 | 52 | "type": "ref/prompt",
3263 | 53 | "name": "code_review"
3264 | 54 | },
3265 | 55 | "argument": {
3266 | 56 | "name": "language",
3267 | 57 | "value": "py"
3268 | 58 | }
3269 | 59 | }
3270 | 60 | }
3271 | 61 | ```
3272 | 62 |
3273 | 63 | **Response:**
3274 | 64 |
3275 | 65 | ```json
3276 | 66 | {
3277 | 67 | "jsonrpc": "2.0",
3278 | 68 | "id": 1,
3279 | 69 | "result": {
3280 | 70 | "completion": {
3281 | 71 | "values": ["python", "pytorch", "pyside"],
3282 | 72 | "total": 10,
3283 | 73 | "hasMore": true
3284 | 74 | }
3285 | 75 | }
3286 | 76 | }
3287 | 77 | ```
3288 | 78 |
3289 | 79 | ### Reference Types
3290 | 80 |
3291 | 81 | The protocol supports two types of completion references:
3292 | 82 |
3293 | 83 | | Type | Description | Example |
3294 | 84 | | -------------- | --------------------------- | --------------------------------------------------- |
3295 | 85 | | `ref/prompt` | References a prompt by name | `{"type": "ref/prompt", "name": "code_review"}` |
3296 | 86 | | `ref/resource` | References a resource URI | `{"type": "ref/resource", "uri": "file:///{path}"}` |
3297 | 87 |
3298 | 88 | ### Completion Results
3299 | 89 |
3300 | 90 | Servers return an array of completion values ranked by relevance, with:
3301 | 91 |
3302 | 92 | - Maximum 100 items per response
3303 | 93 | - Optional total number of available matches
3304 | 94 | - Boolean indicating if additional results exist
3305 | 95 |
3306 | 96 | ## Message Flow
3307 | 97 |
3308 | 98 | ```mermaid
3309 | 99 | sequenceDiagram
3310 | 100 | participant Client
3311 | 101 | participant Server
3312 | 102 |
3313 | 103 | Note over Client: User types argument
3314 | 104 | Client->>Server: completion/complete
3315 | 105 | Server-->>Client: Completion suggestions
3316 | 106 |
3317 | 107 | Note over Client: User continues typing
3318 | 108 | Client->>Server: completion/complete
3319 | 109 | Server-->>Client: Refined suggestions
3320 | 110 | ```
3321 | 111 |
3322 | 112 | ## Data Types
3323 | 113 |
3324 | 114 | ### CompleteRequest
3325 | 115 |
3326 | 116 | - `ref`: A `PromptReference` or `ResourceReference`
3327 | 117 | - `argument`: Object containing:
3328 | 118 | - `name`: Argument name
3329 | 119 | - `value`: Current value
3330 | 120 |
3331 | 121 | ### CompleteResult
3332 | 122 |
3333 | 123 | - `completion`: Object containing:
3334 | 124 | - `values`: Array of suggestions (max 100)
3335 | 125 | - `total`: Optional total matches
3336 | 126 | - `hasMore`: Additional results flag
3337 | 127 |
3338 | 128 | ## Error Handling
3339 | 129 |
3340 | 130 | Servers **SHOULD** return standard JSON-RPC errors for common failure cases:
3341 | 131 |
3342 | 132 | - Method not found: `-32601` (Capability not supported)
3343 | 133 | - Invalid prompt name: `-32602` (Invalid params)
3344 | 134 | - Missing required arguments: `-32602` (Invalid params)
3345 | 135 | - Internal errors: `-32603` (Internal error)
3346 | 136 |
3347 | 137 | ## Implementation Considerations
3348 | 138 |
3349 | 139 | 1. Servers **SHOULD**:
3350 | 140 |
3351 | 141 | - Return suggestions sorted by relevance
3352 | 142 | - Implement fuzzy matching where appropriate
3353 | 143 | - Rate limit completion requests
3354 | 144 | - Validate all inputs
3355 | 145 |
3356 | 146 | 2. Clients **SHOULD**:
3357 | 147 | - Debounce rapid completion requests
3358 | 148 | - Cache completion results where appropriate
3359 | 149 | - Handle missing or partial results gracefully
3360 | 150 |
3361 | 151 | ## Security
3362 | 152 |
3363 | 153 | Implementations **MUST**:
3364 | 154 |
3365 | 155 | - Validate all completion inputs
3366 | 156 | - Implement appropriate rate limiting
3367 | 157 | - Control access to sensitive suggestions
3368 | 158 | - Prevent completion-based information disclosure
3369 | 159 |
3370 |
3371 |
3372 | --------------------------------------------------------------------------------
3373 | /docs/specification/2025-03-26/server/utilities/logging.md:
3374 | --------------------------------------------------------------------------------
3375 | 1 | ---
3376 | 2 | title: Logging
3377 | 3 | ---
3378 | 4 |
3379 | 5 | {{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}}
3380 | 6 |
3381 | 7 | The Model Context Protocol (MCP) provides a standardized way for servers to send
3382 | 8 | structured log messages to clients. Clients can control logging verbosity by setting
3383 | 9 | minimum log levels, with servers sending notifications containing severity levels,
3384 | 10 | optional logger names, and arbitrary JSON-serializable data.
3385 | 11 |
3386 | 12 | ## User Interaction Model
3387 | 13 |
3388 | 14 | Implementations are free to expose logging through any interface pattern that suits their
3389 | 15 | needs—the protocol itself does not mandate any specific user interaction model.
3390 | 16 |
3391 | 17 | ## Capabilities
3392 | 18 |
3393 | 19 | Servers that emit log message notifications **MUST** declare the `logging` capability:
3394 | 20 |
3395 | 21 | ```json
3396 | 22 | {
3397 | 23 | "capabilities": {
3398 | 24 | "logging": {}
3399 | 25 | }
3400 | 26 | }
3401 | 27 | ```
3402 | 28 |
3403 | 29 | ## Log Levels
3404 | 30 |
3405 | 31 | The protocol follows the standard syslog severity levels specified in
3406 | 32 | [RFC 5424](https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1):
3407 | 33 |
3408 | 34 | | Level | Description | Example Use Case |
3409 | 35 | | --------- | -------------------------------- | -------------------------- |
3410 | 36 | | debug | Detailed debugging information | Function entry/exit points |
3411 | 37 | | info | General informational messages | Operation progress updates |
3412 | 38 | | notice | Normal but significant events | Configuration changes |
3413 | 39 | | warning | Warning conditions | Deprecated feature usage |
3414 | 40 | | error | Error conditions | Operation failures |
3415 | 41 | | critical | Critical conditions | System component failures |
3416 | 42 | | alert | Action must be taken immediately | Data corruption detected |
3417 | 43 | | emergency | System is unusable | Complete system failure |
3418 | 44 |
3419 | 45 | ## Protocol Messages
3420 | 46 |
3421 | 47 | ### Setting Log Level
3422 | 48 |
3423 | 49 | To configure the minimum log level, clients **MAY** send a `logging/setLevel` request:
3424 | 50 |
3425 | 51 | **Request:**
3426 | 52 |
3427 | 53 | ```json
3428 | 54 | {
3429 | 55 | "jsonrpc": "2.0",
3430 | 56 | "id": 1,
3431 | 57 | "method": "logging/setLevel",
3432 | 58 | "params": {
3433 | 59 | "level": "info"
3434 | 60 | }
3435 | 61 | }
3436 | 62 | ```
3437 | 63 |
3438 | 64 | ### Log Message Notifications
3439 | 65 |
3440 | 66 | Servers send log messages using `notifications/message` notifications:
3441 | 67 |
3442 | 68 | ```json
3443 | 69 | {
3444 | 70 | "jsonrpc": "2.0",
3445 | 71 | "method": "notifications/message",
3446 | 72 | "params": {
3447 | 73 | "level": "error",
3448 | 74 | "logger": "database",
3449 | 75 | "data": {
3450 | 76 | "error": "Connection failed",
3451 | 77 | "details": {
3452 | 78 | "host": "localhost",
3453 | 79 | "port": 5432
3454 | 80 | }
3455 | 81 | }
3456 | 82 | }
3457 | 83 | }
3458 | 84 | ```
3459 | 85 |
3460 | 86 | ## Message Flow
3461 | 87 |
3462 | 88 | ```mermaid
3463 | 89 | sequenceDiagram
3464 | 90 | participant Client
3465 | 91 | participant Server
3466 | 92 |
3467 | 93 | Note over Client,Server: Configure Logging
3468 | 94 | Client->>Server: logging/setLevel (info)
3469 | 95 | Server-->>Client: Empty Result
3470 | 96 |
3471 | 97 | Note over Client,Server: Server Activity
3472 | 98 | Server--)Client: notifications/message (info)
3473 | 99 | Server--)Client: notifications/message (warning)
3474 | 100 | Server--)Client: notifications/message (error)
3475 | 101 |
3476 | 102 | Note over Client,Server: Level Change
3477 | 103 | Client->>Server: logging/setLevel (error)
3478 | 104 | Server-->>Client: Empty Result
3479 | 105 | Note over Server: Only sends error level<br/>and above
3480 | 106 | ```
3481 | 107 |
3482 | 108 | ## Error Handling
3483 | 109 |
3484 | 110 | Servers **SHOULD** return standard JSON-RPC errors for common failure cases:
3485 | 111 |
3486 | 112 | - Invalid log level: `-32602` (Invalid params)
3487 | 113 | - Configuration errors: `-32603` (Internal error)
3488 | 114 |
3489 | 115 | ## Implementation Considerations
3490 | 116 |
3491 | 117 | 1. Servers **SHOULD**:
3492 | 118 |
3493 | 119 | - Rate limit log messages
3494 | 120 | - Include relevant context in data field
3495 | 121 | - Use consistent logger names
3496 | 122 | - Remove sensitive information
3497 | 123 |
3498 | 124 | 2. Clients **MAY**:
3499 | 125 | - Present log messages in the UI
3500 | 126 | - Implement log filtering/search
3501 | 127 | - Display severity visually
3502 | 128 | - Persist log messages
3503 | 129 |
3504 | 130 | ## Security
3505 | 131 |
3506 | 132 | 1. Log messages **MUST NOT** contain:
3507 | 133 |
3508 | 134 | - Credentials or secrets
3509 | 135 | - Personal identifying information
3510 | 136 | - Internal system details that could aid attacks
3511 | 137 |
3512 | 138 | 2. Implementations **SHOULD**:
3513 | 139 | - Rate limit messages
3514 | 140 | - Validate all data fields
3515 | 141 | - Control log access
3516 | 142 | - Monitor for sensitive content
3517 | 143 |
3518 |
3519 |
3520 | --------------------------------------------------------------------------------
3521 | /docs/specification/2025-03-26/server/utilities/pagination.md:
3522 | --------------------------------------------------------------------------------
3523 | 1 | ---
3524 | 2 | title: Pagination
3525 | 3 | ---
3526 | 4 |
3527 | 5 | {{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}}
3528 | 6 |
3529 | 7 | The Model Context Protocol (MCP) supports paginating list operations that may return
3530 | 8 | large result sets. Pagination allows servers to yield results in smaller chunks rather
3531 | 9 | than all at once.
3532 | 10 |
3533 | 11 | Pagination is especially important when connecting to external services over the
3534 | 12 | internet, but also useful for local integrations to avoid performance issues with large
3535 | 13 | data sets.
3536 | 14 |
3537 | 15 | ## Pagination Model
3538 | 16 |
3539 | 17 | Pagination in MCP uses an opaque cursor-based approach, instead of numbered pages.
3540 | 18 |
3541 | 19 | - The **cursor** is an opaque string token, representing a position in the result set
3542 | 20 | - **Page size** is determined by the server, and **MAY NOT** be fixed
3543 | 21 |
3544 | 22 | ## Response Format
3545 | 23 |
3546 | 24 | Pagination starts when the server sends a **response** that includes:
3547 | 25 |
3548 | 26 | - The current page of results
3549 | 27 | - An optional `nextCursor` field if more results exist
3550 | 28 |
3551 | 29 | ```json
3552 | 30 | {
3553 | 31 | "jsonrpc": "2.0",
3554 | 32 | "id": "123",
3555 | 33 | "result": {
3556 | 34 | "resources": [...],
3557 | 35 | "nextCursor": "eyJwYWdlIjogM30="
3558 | 36 | }
3559 | 37 | }
3560 | 38 | ```
3561 | 39 |
3562 | 40 | ## Request Format
3563 | 41 |
3564 | 42 | After receiving a cursor, the client can _continue_ paginating by issuing a request
3565 | 43 | including that cursor:
3566 | 44 |
3567 | 45 | ```json
3568 | 46 | {
3569 | 47 | "jsonrpc": "2.0",
3570 | 48 | "method": "resources/list",
3571 | 49 | "params": {
3572 | 50 | "cursor": "eyJwYWdlIjogMn0="
3573 | 51 | }
3574 | 52 | }
3575 | 53 | ```
3576 | 54 |
3577 | 55 | ## Pagination Flow
3578 | 56 |
3579 | 57 | ```mermaid
3580 | 58 | sequenceDiagram
3581 | 59 | participant Client
3582 | 60 | participant Server
3583 | 61 |
3584 | 62 | Client->>Server: List Request (no cursor)
3585 | 63 | loop Pagination Loop
3586 | 64 | Server-->>Client: Page of results + nextCursor
3587 | 65 | Client->>Server: List Request (with cursor)
3588 | 66 | end
3589 | 67 | ```
3590 | 68 |
3591 | 69 | ## Operations Supporting Pagination
3592 | 70 |
3593 | 71 | The following MCP operations support pagination:
3594 | 72 |
3595 | 73 | - `resources/list` - List available resources
3596 | 74 | - `resources/templates/list` - List resource templates
3597 | 75 | - `prompts/list` - List available prompts
3598 | 76 | - `tools/list` - List available tools
3599 | 77 |
3600 | 78 | ## Implementation Guidelines
3601 | 79 |
3602 | 80 | 1. Servers **SHOULD**:
3603 | 81 |
3604 | 82 | - Provide stable cursors
3605 | 83 | - Handle invalid cursors gracefully
3606 | 84 |
3607 | 85 | 2. Clients **SHOULD**:
3608 | 86 |
3609 | 87 | - Treat a missing `nextCursor` as the end of results
3610 | 88 | - Support both paginated and non-paginated flows
3611 | 89 |
3612 | 90 | 3. Clients **MUST** treat cursors as opaque tokens:
3613 | 91 | - Don't make assumptions about cursor format
3614 | 92 | - Don't attempt to parse or modify cursors
3615 | 93 | - Don't persist cursors across sessions
3616 | 94 |
3617 | 95 | ## Error Handling
3618 | 96 |
3619 | 97 | Invalid cursors **SHOULD** result in an error with code -32602 (Invalid params).
3620 | 98 |
3621 |
3622 |
3623 | --------------------------------------------------------------------------------
3624 |
```