this repo has no description
add SPEC mirrors
+2006
+178
spec/00-arch.md
+178
spec/00-arch.md
···
1
+
---
2
+
title: Architecture
3
+
cascade:
4
+
type: docs
5
+
weight: 10
6
+
---
7
+
8
+
The Model Context Protocol (MCP) follows a client-host-server architecture where each
9
+
host can run multiple client instances. This architecture enables users to integrate AI
10
+
capabilities across applications while maintaining clear security boundaries and
11
+
isolating concerns. Built on JSON-RPC, MCP provides a stateful session protocol focused
12
+
on context exchange and sampling coordination between clients and servers.
13
+
14
+
## Core Components
15
+
16
+
```mermaid
17
+
graph LR
18
+
subgraph "Application Host Process"
19
+
H[Host]
20
+
C1[Client 1]
21
+
C2[Client 2]
22
+
C3[Client 3]
23
+
H --> C1
24
+
H --> C2
25
+
H --> C3
26
+
end
27
+
28
+
subgraph "Local machine"
29
+
S1[Server 1<br>Files & Git]
30
+
S2[Server 2<br>Database]
31
+
R1[("Local<br>Resource A")]
32
+
R2[("Local<br>Resource B")]
33
+
34
+
C1 --> S1
35
+
C2 --> S2
36
+
S1 <--> R1
37
+
S2 <--> R2
38
+
end
39
+
40
+
subgraph "Internet"
41
+
S3[Server 3<br>External APIs]
42
+
R3[("Remote<br>Resource C")]
43
+
44
+
C3 --> S3
45
+
S3 <--> R3
46
+
end
47
+
```
48
+
49
+
### Host
50
+
51
+
The host process acts as the container and coordinator:
52
+
53
+
- Creates and manages multiple client instances
54
+
- Controls client connection permissions and lifecycle
55
+
- Enforces security policies and consent requirements
56
+
- Handles user authorization decisions
57
+
- Coordinates AI/LLM integration and sampling
58
+
- Manages context aggregation across clients
59
+
60
+
### Clients
61
+
62
+
Each client is created by the host and maintains an isolated server connection:
63
+
64
+
- Establishes one stateful session per server
65
+
- Handles protocol negotiation and capability exchange
66
+
- Routes protocol messages bidirectionally
67
+
- Manages subscriptions and notifications
68
+
- Maintains security boundaries between servers
69
+
70
+
A host application creates and manages multiple clients, with each client having a 1:1
71
+
relationship with a particular server.
72
+
73
+
### Servers
74
+
75
+
Servers provide specialized context and capabilities:
76
+
77
+
- Expose resources, tools and prompts via MCP primitives
78
+
- Operate independently with focused responsibilities
79
+
- Request sampling through client interfaces
80
+
- Must respect security constraints
81
+
- Can be local processes or remote services
82
+
83
+
## Design Principles
84
+
85
+
MCP is built on several key design principles that inform its architecture and
86
+
implementation:
87
+
88
+
1. **Servers should be extremely easy to build**
89
+
90
+
- Host applications handle complex orchestration responsibilities
91
+
- Servers focus on specific, well-defined capabilities
92
+
- Simple interfaces minimize implementation overhead
93
+
- Clear separation enables maintainable code
94
+
95
+
2. **Servers should be highly composable**
96
+
97
+
- Each server provides focused functionality in isolation
98
+
- Multiple servers can be combined seamlessly
99
+
- Shared protocol enables interoperability
100
+
- Modular design supports extensibility
101
+
102
+
3. **Servers should not be able to read the whole conversation, nor "see into" other
103
+
servers**
104
+
105
+
- Servers receive only necessary contextual information
106
+
- Full conversation history stays with the host
107
+
- Each server connection maintains isolation
108
+
- Cross-server interactions are controlled by the host
109
+
- Host process enforces security boundaries
110
+
111
+
4. **Features can be added to servers and clients progressively**
112
+
- Core protocol provides minimal required functionality
113
+
- Additional capabilities can be negotiated as needed
114
+
- Servers and clients evolve independently
115
+
- Protocol designed for future extensibility
116
+
- Backwards compatibility is maintained
117
+
118
+
## Capability Negotiation
119
+
120
+
The Model Context Protocol uses a capability-based negotiation system where clients and
121
+
servers explicitly declare their supported features during initialization. Capabilities
122
+
determine which protocol features and primitives are available during a session.
123
+
124
+
- Servers declare capabilities like resource subscriptions, tool support, and prompt
125
+
templates
126
+
- Clients declare capabilities like sampling support and notification handling
127
+
- Both parties must respect declared capabilities throughout the session
128
+
- Additional capabilities can be negotiated through extensions to the protocol
129
+
130
+
```mermaid
131
+
sequenceDiagram
132
+
participant Host
133
+
participant Client
134
+
participant Server
135
+
136
+
Host->>+Client: Initialize client
137
+
Client->>+Server: Initialize session with capabilities
138
+
Server-->>Client: Respond with supported capabilities
139
+
140
+
Note over Host,Server: Active Session with Negotiated Features
141
+
142
+
loop Client Requests
143
+
Host->>Client: User- or model-initiated action
144
+
Client->>Server: Request (tools/resources)
145
+
Server-->>Client: Response
146
+
Client-->>Host: Update UI or respond to model
147
+
end
148
+
149
+
loop Server Requests
150
+
Server->>Client: Request (sampling)
151
+
Client->>Host: Forward to AI
152
+
Host-->>Client: AI response
153
+
Client-->>Server: Response
154
+
end
155
+
156
+
loop Notifications
157
+
Server--)Client: Resource updates
158
+
Client--)Server: Status changes
159
+
end
160
+
161
+
Host->>Client: Terminate
162
+
Client->>-Server: End session
163
+
deactivate Server
164
+
```
165
+
166
+
Each capability unlocks specific protocol features for use during the session. For
167
+
example:
168
+
169
+
- Implemented [server features]({{< ref "../server" >}}) must be advertised in the
170
+
server's capabilities
171
+
- Emitting resource subscription notifications requires the server to declare
172
+
subscription support
173
+
- Tool invocation requires the server to declare tool capabilities
174
+
- [Sampling]({{< ref "../client" >}}) requires the client to declare support in its
175
+
capabilities
176
+
177
+
This capability negotiation ensures clients and servers have a clear understanding of
178
+
supported functionality while maintaining protocol extensibility.
+4
spec/README.md
+4
spec/README.md
+239
spec/lifecycle.md
+239
spec/lifecycle.md
···
1
+
---
2
+
title: Lifecycle
3
+
type: docs
4
+
weight: 30
5
+
---
6
+
7
+
{{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}}
8
+
9
+
The Model Context Protocol (MCP) defines a rigorous lifecycle for client-server
10
+
connections that ensures proper capability negotiation and state management.
11
+
12
+
1. **Initialization**: Capability negotiation and protocol version agreement
13
+
2. **Operation**: Normal protocol communication
14
+
3. **Shutdown**: Graceful termination of the connection
15
+
16
+
```mermaid
17
+
sequenceDiagram
18
+
participant Client
19
+
participant Server
20
+
21
+
Note over Client,Server: Initialization Phase
22
+
activate Client
23
+
Client->>+Server: initialize request
24
+
Server-->>Client: initialize response
25
+
Client--)Server: initialized notification
26
+
27
+
Note over Client,Server: Operation Phase
28
+
rect rgb(200, 220, 250)
29
+
note over Client,Server: Normal protocol operations
30
+
end
31
+
32
+
Note over Client,Server: Shutdown
33
+
Client--)-Server: Disconnect
34
+
deactivate Server
35
+
Note over Client,Server: Connection closed
36
+
```
37
+
38
+
## Lifecycle Phases
39
+
40
+
### Initialization
41
+
42
+
The initialization phase **MUST** be the first interaction between client and server.
43
+
During this phase, the client and server:
44
+
45
+
- Establish protocol version compatibility
46
+
- Exchange and negotiate capabilities
47
+
- Share implementation details
48
+
49
+
The client **MUST** initiate this phase by sending an `initialize` request containing:
50
+
51
+
- Protocol version supported
52
+
- Client capabilities
53
+
- Client implementation information
54
+
55
+
```json
56
+
{
57
+
"jsonrpc": "2.0",
58
+
"id": 1,
59
+
"method": "initialize",
60
+
"params": {
61
+
"protocolVersion": "2024-11-05",
62
+
"capabilities": {
63
+
"roots": {
64
+
"listChanged": true
65
+
},
66
+
"sampling": {}
67
+
},
68
+
"clientInfo": {
69
+
"name": "ExampleClient",
70
+
"version": "1.0.0"
71
+
}
72
+
}
73
+
}
74
+
```
75
+
76
+
The initialize request **MUST NOT** be part of a JSON-RPC
77
+
[batch](https://www.jsonrpc.org/specification#batch), as other requests and notifications
78
+
are not possible until initialization has completed. This also permits backwards
79
+
compatibility with prior protocol versions that do not explicitly support JSON-RPC
80
+
batches.
81
+
82
+
The server **MUST** respond with its own capabilities and information:
83
+
84
+
```json
85
+
{
86
+
"jsonrpc": "2.0",
87
+
"id": 1,
88
+
"result": {
89
+
"protocolVersion": "2024-11-05",
90
+
"capabilities": {
91
+
"logging": {},
92
+
"prompts": {
93
+
"listChanged": true
94
+
},
95
+
"resources": {
96
+
"subscribe": true,
97
+
"listChanged": true
98
+
},
99
+
"tools": {
100
+
"listChanged": true
101
+
}
102
+
},
103
+
"serverInfo": {
104
+
"name": "ExampleServer",
105
+
"version": "1.0.0"
106
+
}
107
+
}
108
+
}
109
+
```
110
+
111
+
After successful initialization, the client **MUST** send an `initialized` notification
112
+
to indicate it is ready to begin normal operations:
113
+
114
+
```json
115
+
{
116
+
"jsonrpc": "2.0",
117
+
"method": "notifications/initialized"
118
+
}
119
+
```
120
+
121
+
- The client **SHOULD NOT** send requests other than
122
+
[pings]({{< ref "utilities/ping" >}}) before the server has responded to the
123
+
`initialize` request.
124
+
- The server **SHOULD NOT** send requests other than
125
+
[pings]({{< ref "utilities/ping" >}}) and
126
+
[logging]({{< ref "../server/utilities/logging" >}}) before receiving the `initialized`
127
+
notification.
128
+
129
+
#### Version Negotiation
130
+
131
+
In the `initialize` request, the client **MUST** send a protocol version it supports.
132
+
This **SHOULD** be the _latest_ version supported by the client.
133
+
134
+
If the server supports the requested protocol version, it **MUST** respond with the same
135
+
version. Otherwise, the server **MUST** respond with another protocol version it
136
+
supports. This **SHOULD** be the _latest_ version supported by the server.
137
+
138
+
If the client does not support the version in the server's response, it **SHOULD**
139
+
disconnect.
140
+
141
+
#### Capability Negotiation
142
+
143
+
Client and server capabilities establish which optional protocol features will be
144
+
available during the session.
145
+
146
+
Key capabilities include:
147
+
148
+
| Category | Capability | Description |
149
+
| -------- | -------------- | -------------------------------------------------------------------------- |
150
+
| Client | `roots` | Ability to provide filesystem [roots]({{< ref "../client/roots" >}}) |
151
+
| Client | `sampling` | Support for LLM [sampling]({{< ref "../client/sampling" >}}) requests |
152
+
| Client | `experimental` | Describes support for non-standard experimental features |
153
+
| Server | `prompts` | Offers [prompt templates]({{< ref "../server/prompts" >}}) |
154
+
| Server | `resources` | Provides readable [resources]({{< ref "../server/resources" >}}) |
155
+
| Server | `tools` | Exposes callable [tools]({{< ref "../server/tools" >}}) |
156
+
| Server | `logging` | Emits structured [log messages]({{< ref "../server/utilities/logging" >}}) |
157
+
| Server | `experimental` | Describes support for non-standard experimental features |
158
+
159
+
Capability objects can describe sub-capabilities like:
160
+
161
+
- `listChanged`: Support for list change notifications (for prompts, resources, and
162
+
tools)
163
+
- `subscribe`: Support for subscribing to individual items' changes (resources only)
164
+
165
+
### Operation
166
+
167
+
During the operation phase, the client and server exchange messages according to the
168
+
negotiated capabilities.
169
+
170
+
Both parties **SHOULD**:
171
+
172
+
- Respect the negotiated protocol version
173
+
- Only use capabilities that were successfully negotiated
174
+
175
+
### Shutdown
176
+
177
+
During the shutdown phase, one side (usually the client) cleanly terminates the protocol
178
+
connection. No specific shutdown messages are defined—instead, the underlying transport
179
+
mechanism should be used to signal connection termination:
180
+
181
+
#### stdio
182
+
183
+
For the stdio [transport]({{< ref "transports" >}}), the client **SHOULD** initiate
184
+
shutdown by:
185
+
186
+
1. First, closing the input stream to the child process (the server)
187
+
2. Waiting for the server to exit, or sending `SIGTERM` if the server does not exit
188
+
within a reasonable time
189
+
3. Sending `SIGKILL` if the server does not exit within a reasonable time after `SIGTERM`
190
+
191
+
The server **MAY** initiate shutdown by closing its output stream to the client and
192
+
exiting.
193
+
194
+
#### HTTP
195
+
196
+
For HTTP [transports]({{< ref "transports" >}}), shutdown is indicated by closing the
197
+
associated HTTP connection(s).
198
+
199
+
## Timeouts
200
+
201
+
Implementations **SHOULD** establish timeouts for all sent requests, to prevent hung
202
+
connections and resource exhaustion. When the request has not received a success or error
203
+
response within the timeout period, the sender **SHOULD** issue a [cancellation
204
+
notification]({{< ref "utilities/cancellation" >}}) for that request and stop waiting for
205
+
a response.
206
+
207
+
SDKs and other middleware **SHOULD** allow these timeouts to be configured on a
208
+
per-request basis.
209
+
210
+
Implementations **MAY** choose to reset the timeout clock when receiving a [progress
211
+
notification]({{< ref "utilities/progress" >}}) corresponding to the request, as this
212
+
implies that work is actually happening. However, implementations **SHOULD** always
213
+
enforce a maximum timeout, regardless of progress notifications, to limit the impact of a
214
+
misbehaving client or server.
215
+
216
+
## Error Handling
217
+
218
+
Implementations **SHOULD** be prepared to handle these error cases:
219
+
220
+
- Protocol version mismatch
221
+
- Failure to negotiate required capabilities
222
+
- Request [timeouts](#timeouts)
223
+
224
+
Example initialization error:
225
+
226
+
```json
227
+
{
228
+
"jsonrpc": "2.0",
229
+
"id": 1,
230
+
"error": {
231
+
"code": -32602,
232
+
"message": "Unsupported protocol version",
233
+
"data": {
234
+
"supported": ["2024-11-05"],
235
+
"requested": "1.0.0"
236
+
}
237
+
}
238
+
}
239
+
```
+265
spec/prompts.md
+265
spec/prompts.md
···
1
+
---
2
+
title: Prompts
3
+
weight: 10
4
+
---
5
+
6
+
{{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}}
7
+
8
+
The Model Context Protocol (MCP) provides a standardized way for servers to expose prompt
9
+
templates to clients. Prompts allow servers to provide structured messages and
10
+
instructions for interacting with language models. Clients can discover available
11
+
prompts, retrieve their contents, and provide arguments to customize them.
12
+
13
+
## User Interaction Model
14
+
15
+
Prompts are designed to be **user-controlled**, meaning they are exposed from servers to
16
+
clients with the intention of the user being able to explicitly select them for use.
17
+
18
+
Typically, prompts would be triggered through user-initiated commands in the user
19
+
interface, which allows users to naturally discover and invoke available prompts.
20
+
21
+
For example, as slash commands:
22
+
23
+
24
+
25
+
However, implementors are free to expose prompts through any interface pattern that suits
26
+
their needs—the protocol itself does not mandate any specific user interaction
27
+
model.
28
+
29
+
## Capabilities
30
+
31
+
Servers that support prompts **MUST** declare the `prompts` capability during
32
+
[initialization]({{< ref "../basic/lifecycle#initialization" >}}):
33
+
34
+
/draft`json { "capabilities": { "prompts": { "listChanged": true } } }
35
+
36
+
````
37
+
38
+
`listChanged` indicates whether the server will emit notifications when the list of
39
+
available prompts changes.
40
+
41
+
## Protocol Messages
42
+
43
+
### Listing Prompts
44
+
45
+
To retrieve available prompts, clients send a `prompts/list` request. This operation
46
+
supports [pagination]({{< ref "utilities/pagination" >}}).
47
+
48
+
**Request:**
49
+
50
+
```json
51
+
{
52
+
"jsonrpc": "2.0",
53
+
"id": 1,
54
+
"method": "prompts/list",
55
+
"params": {
56
+
"cursor": "optional-cursor-value"
57
+
}
58
+
}
59
+
````
60
+
61
+
**Response:**
62
+
63
+
```json
64
+
{
65
+
"jsonrpc": "2.0",
66
+
"id": 1,
67
+
"result": {
68
+
"prompts": [
69
+
{
70
+
"name": "code_review",
71
+
"description": "Asks the LLM to analyze code quality and suggest improvements",
72
+
"arguments": [
73
+
{
74
+
"name": "code",
75
+
"description": "The code to review",
76
+
"required": true
77
+
}
78
+
]
79
+
}
80
+
],
81
+
"nextCursor": "next-page-cursor"
82
+
}
83
+
}
84
+
```
85
+
86
+
### Getting a Prompt
87
+
88
+
To retrieve a specific prompt, clients send a `prompts/get` request. Arguments may be
89
+
auto-completed through [the completion API]({{< ref "utilities/completion" >}}).
90
+
91
+
**Request:**
92
+
93
+
```json
94
+
{
95
+
"jsonrpc": "2.0",
96
+
"id": 2,
97
+
"method": "prompts/get",
98
+
"params": {
99
+
"name": "code_review",
100
+
"arguments": {
101
+
"code": "def hello():\n print('world')"
102
+
}
103
+
}
104
+
}
105
+
```
106
+
107
+
**Response:**
108
+
109
+
```json
110
+
{
111
+
"jsonrpc": "2.0",
112
+
"id": 2,
113
+
"result": {
114
+
"description": "Code review prompt",
115
+
"messages": [
116
+
{
117
+
"role": "user",
118
+
"content": {
119
+
"type": "text",
120
+
"text": "Please review this Python code:\ndef hello():\n print('world')"
121
+
}
122
+
}
123
+
]
124
+
}
125
+
}
126
+
```
127
+
128
+
### List Changed Notification
129
+
130
+
When the list of available prompts changes, servers that declared the `listChanged`
131
+
capability **SHOULD** send a notification:
132
+
133
+
```json
134
+
{
135
+
"jsonrpc": "2.0",
136
+
"method": "notifications/prompts/list_changed"
137
+
}
138
+
```
139
+
140
+
## Message Flow
141
+
142
+
```mermaid
143
+
sequenceDiagram
144
+
participant Client
145
+
participant Server
146
+
147
+
Note over Client,Server: Discovery
148
+
Client->>Server: prompts/list
149
+
Server-->>Client: List of prompts
150
+
151
+
Note over Client,Server: Usage
152
+
Client->>Server: prompts/get
153
+
Server-->>Client: Prompt content
154
+
155
+
opt listChanged
156
+
Note over Client,Server: Changes
157
+
Server--)Client: prompts/list_changed
158
+
Client->>Server: prompts/list
159
+
Server-->>Client: Updated prompts
160
+
end
161
+
```
162
+
163
+
## Data Types
164
+
165
+
### Prompt
166
+
167
+
A prompt definition includes:
168
+
169
+
- `name`: Unique identifier for the prompt
170
+
- `description`: Optional human-readable description
171
+
- `arguments`: Optional list of arguments for customization
172
+
173
+
### PromptMessage
174
+
175
+
Messages in a prompt can contain:
176
+
177
+
- `role`: Either "user" or "assistant" to indicate the speaker
178
+
- `content`: One of the following content types:
179
+
180
+
#### Text Content
181
+
182
+
Text content represents plain text messages:
183
+
184
+
```json
185
+
{
186
+
"type": "text",
187
+
"text": "The text content of the message"
188
+
}
189
+
```
190
+
191
+
This is the most common content type used for natural language interactions.
192
+
193
+
#### Image Content
194
+
195
+
Image content allows including visual information in messages:
196
+
197
+
```json
198
+
{
199
+
"type": "image",
200
+
"data": "base64-encoded-image-data",
201
+
"mimeType": "image/png"
202
+
}
203
+
```
204
+
205
+
The image data **MUST** be base64-encoded and include a valid MIME type. This enables
206
+
multi-modal interactions where visual context is important.
207
+
208
+
#### Audio Content
209
+
210
+
Audio content allows including audio information in messages:
211
+
212
+
```json
213
+
{
214
+
"type": "audio",
215
+
"data": "base64-encoded-audio-data",
216
+
"mimeType": "audio/wav"
217
+
}
218
+
```
219
+
220
+
The audio data MUST be base64-encoded and include a valid MIME type. This enables
221
+
multi-modal interactions where audio context is important.
222
+
223
+
#### Embedded Resources
224
+
225
+
Embedded resources allow referencing server-side resources directly in messages:
226
+
227
+
```json
228
+
{
229
+
"type": "resource",
230
+
"resource": {
231
+
"uri": "resource://example",
232
+
"mimeType": "text/plain",
233
+
"text": "Resource content"
234
+
}
235
+
}
236
+
```
237
+
238
+
Resources can contain either text or binary (blob) data and **MUST** include:
239
+
240
+
- A valid resource URI
241
+
- The appropriate MIME type
242
+
- Either text content or base64-encoded blob data
243
+
244
+
Embedded resources enable prompts to seamlessly incorporate server-managed content like
245
+
documentation, code samples, or other reference materials directly into the conversation
246
+
flow.
247
+
248
+
## Error Handling
249
+
250
+
Servers **SHOULD** return standard JSON-RPC errors for common failure cases:
251
+
252
+
- Invalid prompt name: `-32602` (Invalid params)
253
+
- Missing required arguments: `-32602` (Invalid params)
254
+
- Internal errors: `-32603` (Internal error)
255
+
256
+
## Implementation Considerations
257
+
258
+
1. Servers **SHOULD** validate prompt arguments before processing
259
+
2. Clients **SHOULD** handle pagination for large prompt lists
260
+
3. Both parties **SHOULD** respect capability negotiation
261
+
262
+
## Security
263
+
264
+
Implementations **MUST** carefully validate all prompt inputs and outputs to prevent
265
+
injection attacks or unauthorized access to resources.
+357
spec/resources.md
+357
spec/resources.md
···
1
+
---
2
+
title: Resources
3
+
type: docs
4
+
weight: 20
5
+
---
6
+
7
+
{{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}}
8
+
9
+
The Model Context Protocol (MCP) provides a standardized way for servers to expose
10
+
resources to clients. Resources allow servers to share data that provides context to
11
+
language models, such as files, database schemas, or application-specific information.
12
+
Each resource is uniquely identified by a
13
+
[URI](https://datatracker.ietf.org/doc/html/rfc3986).
14
+
15
+
## User Interaction Model
16
+
17
+
Resources in MCP are designed to be **application-driven**, with host applications
18
+
determining how to incorporate context based on their needs.
19
+
20
+
For example, applications could:
21
+
22
+
- Expose resources through UI elements for explicit selection, in a tree or list view
23
+
- Allow the user to search through and filter available resources
24
+
- Implement automatic context inclusion, based on heuristics or the AI model's selection
25
+
26
+
27
+
28
+
However, implementations are free to expose resources through any interface pattern that
29
+
suits their needs—the protocol itself does not mandate any specific user
30
+
interaction model.
31
+
32
+
## Capabilities
33
+
34
+
Servers that support resources **MUST** declare the `resources` capability:
35
+
36
+
```json
37
+
{
38
+
"capabilities": {
39
+
"resources": {
40
+
"subscribe": true,
41
+
"listChanged": true
42
+
}
43
+
}
44
+
}
45
+
```
46
+
47
+
The capability supports two optional features:
48
+
49
+
- `subscribe`: whether the client can subscribe to be notified of changes to individual
50
+
resources.
51
+
- `listChanged`: whether the server will emit notifications when the list of available
52
+
resources changes.
53
+
54
+
Both `subscribe` and `listChanged` are optional—servers can support neither,
55
+
either, or both:
56
+
57
+
```json
58
+
{
59
+
"capabilities": {
60
+
"resources": {} // Neither feature supported
61
+
}
62
+
}
63
+
```
64
+
65
+
```json
66
+
{
67
+
"capabilities": {
68
+
"resources": {
69
+
"subscribe": true // Only subscriptions supported
70
+
}
71
+
}
72
+
}
73
+
```
74
+
75
+
```json
76
+
{
77
+
"capabilities": {
78
+
"resources": {
79
+
"listChanged": true // Only list change notifications supported
80
+
}
81
+
}
82
+
}
83
+
```
84
+
85
+
## Protocol Messages
86
+
87
+
### Listing Resources
88
+
89
+
To discover available resources, clients send a `resources/list` request. This operation
90
+
supports [pagination]({{< ref "utilities/pagination" >}}).
91
+
92
+
**Request:**
93
+
94
+
```json
95
+
{
96
+
"jsonrpc": "2.0",
97
+
"id": 1,
98
+
"method": "resources/list",
99
+
"params": {
100
+
"cursor": "optional-cursor-value"
101
+
}
102
+
}
103
+
```
104
+
105
+
**Response:**
106
+
107
+
```json
108
+
{
109
+
"jsonrpc": "2.0",
110
+
"id": 1,
111
+
"result": {
112
+
"resources": [
113
+
{
114
+
"uri": "file:///project/src/main.rs",
115
+
"name": "main.rs",
116
+
"description": "Primary application entry point",
117
+
"mimeType": "text/x-rust"
118
+
}
119
+
],
120
+
"nextCursor": "next-page-cursor"
121
+
}
122
+
}
123
+
```
124
+
125
+
### Reading Resources
126
+
127
+
To retrieve resource contents, clients send a `resources/read` request:
128
+
129
+
**Request:**
130
+
131
+
```json
132
+
{
133
+
"jsonrpc": "2.0",
134
+
"id": 2,
135
+
"method": "resources/read",
136
+
"params": {
137
+
"uri": "file:///project/src/main.rs"
138
+
}
139
+
}
140
+
```
141
+
142
+
**Response:**
143
+
144
+
```json
145
+
{
146
+
"jsonrpc": "2.0",
147
+
"id": 2,
148
+
"result": {
149
+
"contents": [
150
+
{
151
+
"uri": "file:///project/src/main.rs",
152
+
"mimeType": "text/x-rust",
153
+
"text": "fn main() {\n println!(\"Hello world!\");\n}"
154
+
}
155
+
]
156
+
}
157
+
}
158
+
```
159
+
160
+
### Resource Templates
161
+
162
+
Resource templates allow servers to expose parameterized resources using
163
+
[URI templates](https://datatracker.ietf.org/doc/html/rfc6570). Arguments may be
164
+
auto-completed through [the completion API]({{< ref "utilities/completion" >}}).
165
+
166
+
**Request:**
167
+
168
+
```json
169
+
{
170
+
"jsonrpc": "2.0",
171
+
"id": 3,
172
+
"method": "resources/templates/list"
173
+
}
174
+
```
175
+
176
+
**Response:**
177
+
178
+
```json
179
+
{
180
+
"jsonrpc": "2.0",
181
+
"id": 3,
182
+
"result": {
183
+
"resourceTemplates": [
184
+
{
185
+
"uriTemplate": "file:///{path}",
186
+
"name": "Project Files",
187
+
"description": "Access files in the project directory",
188
+
"mimeType": "application/octet-stream"
189
+
}
190
+
]
191
+
}
192
+
}
193
+
```
194
+
195
+
### List Changed Notification
196
+
197
+
When the list of available resources changes, servers that declared the `listChanged`
198
+
capability **SHOULD** send a notification:
199
+
200
+
```json
201
+
{
202
+
"jsonrpc": "2.0",
203
+
"method": "notifications/resources/list_changed"
204
+
}
205
+
```
206
+
207
+
### Subscriptions
208
+
209
+
The protocol supports optional subscriptions to resource changes. Clients can subscribe
210
+
to specific resources and receive notifications when they change:
211
+
212
+
**Subscribe Request:**
213
+
214
+
```json
215
+
{
216
+
"jsonrpc": "2.0",
217
+
"id": 4,
218
+
"method": "resources/subscribe",
219
+
"params": {
220
+
"uri": "file:///project/src/main.rs"
221
+
}
222
+
}
223
+
```
224
+
225
+
**Update Notification:**
226
+
227
+
```json
228
+
{
229
+
"jsonrpc": "2.0",
230
+
"method": "notifications/resources/updated",
231
+
"params": {
232
+
"uri": "file:///project/src/main.rs"
233
+
}
234
+
}
235
+
```
236
+
237
+
## Message Flow
238
+
239
+
```mermaid
240
+
sequenceDiagram
241
+
participant Client
242
+
participant Server
243
+
244
+
Note over Client,Server: Resource Discovery
245
+
Client->>Server: resources/list
246
+
Server-->>Client: List of resources
247
+
248
+
Note over Client,Server: Resource Access
249
+
Client->>Server: resources/read
250
+
Server-->>Client: Resource contents
251
+
252
+
Note over Client,Server: Subscriptions
253
+
Client->>Server: resources/subscribe
254
+
Server-->>Client: Subscription confirmed
255
+
256
+
Note over Client,Server: Updates
257
+
Server--)Client: notifications/resources/updated
258
+
Client->>Server: resources/read
259
+
Server-->>Client: Updated contents
260
+
```
261
+
262
+
## Data Types
263
+
264
+
### Resource
265
+
266
+
A resource definition includes:
267
+
268
+
- `uri`: Unique identifier for the resource
269
+
- `name`: Human-readable name
270
+
- `description`: Optional description
271
+
- `mimeType`: Optional MIME type
272
+
- `size`: Optional size in bytes
273
+
274
+
### Resource Contents
275
+
276
+
Resources can contain either text or binary data:
277
+
278
+
#### Text Content
279
+
280
+
```json
281
+
{
282
+
"uri": "file:///example.txt",
283
+
"mimeType": "text/plain",
284
+
"text": "Resource content"
285
+
}
286
+
```
287
+
288
+
#### Binary Content
289
+
290
+
```json
291
+
{
292
+
"uri": "file:///example.png",
293
+
"mimeType": "image/png",
294
+
"blob": "base64-encoded-data"
295
+
}
296
+
```
297
+
298
+
## Common URI Schemes
299
+
300
+
The protocol defines several standard URI schemes. This list not
301
+
exhaustive—implementations are always free to use additional, custom URI schemes.
302
+
303
+
### https://
304
+
305
+
Used to represent a resource available on the web.
306
+
307
+
Servers **SHOULD** use this scheme only when the client is able to fetch and load the
308
+
resource directly from the web on its own—that is, it doesn’t need to read the resource
309
+
via the MCP server.
310
+
311
+
For other use cases, servers **SHOULD** prefer to use another URI scheme, or define a
312
+
custom one, even if the server will itself be downloading resource contents over the
313
+
internet.
314
+
315
+
### file://
316
+
317
+
Used to identify resources that behave like a filesystem. However, the resources do not
318
+
need to map to an actual physical filesystem.
319
+
320
+
MCP servers **MAY** identify file:// resources with an
321
+
[XDG MIME type](https://specifications.freedesktop.org/shared-mime-info-spec/0.14/ar01s02.html#id-1.3.14),
322
+
like `inode/directory`, to represent non-regular files (such as directories) that don’t
323
+
otherwise have a standard MIME type.
324
+
325
+
### git://
326
+
327
+
Git version control integration.
328
+
329
+
## Error Handling
330
+
331
+
Servers **SHOULD** return standard JSON-RPC errors for common failure cases:
332
+
333
+
- Resource not found: `-32002`
334
+
- Internal errors: `-32603`
335
+
336
+
Example error:
337
+
338
+
```json
339
+
{
340
+
"jsonrpc": "2.0",
341
+
"id": 5,
342
+
"error": {
343
+
"code": -32002,
344
+
"message": "Resource not found",
345
+
"data": {
346
+
"uri": "file:///nonexistent.txt"
347
+
}
348
+
}
349
+
}
350
+
```
351
+
352
+
## Security Considerations
353
+
354
+
1. Servers **MUST** validate all resource URIs
355
+
2. Access controls **SHOULD** be implemented for sensitive resources
356
+
3. Binary data **MUST** be properly encoded
357
+
4. Resource permissions **SHOULD** be checked before operations
spec/slash-command.png
spec/slash-command.png
This is a binary file and will not be displayed.
+299
spec/tools.md
+299
spec/tools.md
···
1
+
---
2
+
title: Tools
3
+
type: docs
4
+
weight: 40
5
+
---
6
+
7
+
{{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}}
8
+
9
+
The Model Context Protocol (MCP) allows servers to expose tools that can be invoked by
10
+
language models. Tools enable models to interact with external systems, such as querying
11
+
databases, calling APIs, or performing computations. Each tool is uniquely identified by
12
+
a name and includes metadata describing its schema.
13
+
14
+
## User Interaction Model
15
+
16
+
Tools in MCP are designed to be **model-controlled**, meaning that the language model can
17
+
discover and invoke tools automatically based on its contextual understanding and the
18
+
user's prompts.
19
+
20
+
However, implementations are free to expose tools through any interface pattern that
21
+
suits their needs—the protocol itself does not mandate any specific user
22
+
interaction model.
23
+
24
+
{{< callout type="warning" >}} For trust & safety and security, there **SHOULD** always
25
+
be a human in the loop with the ability to deny tool invocations.
26
+
27
+
Applications **SHOULD**:
28
+
29
+
- Provide UI that makes clear which tools are being exposed to the AI model
30
+
- Insert clear visual indicators when tools are invoked
31
+
- Present confirmation prompts to the user for operations, to ensure a human is in the
32
+
loop {{< /callout >}}
33
+
34
+
## Capabilities
35
+
36
+
Servers that support tools **MUST** declare the `tools` capability:
37
+
38
+
```json
39
+
{
40
+
"capabilities": {
41
+
"tools": {
42
+
"listChanged": true
43
+
}
44
+
}
45
+
}
46
+
```
47
+
48
+
`listChanged` indicates whether the server will emit notifications when the list of
49
+
available tools changes.
50
+
51
+
## Protocol Messages
52
+
53
+
### Listing Tools
54
+
55
+
To discover available tools, clients send a `tools/list` request. This operation supports
56
+
[pagination]({{< ref "utilities/pagination" >}}).
57
+
58
+
**Request:**
59
+
60
+
```json
61
+
{
62
+
"jsonrpc": "2.0",
63
+
"id": 1,
64
+
"method": "tools/list",
65
+
"params": {
66
+
"cursor": "optional-cursor-value"
67
+
}
68
+
}
69
+
```
70
+
71
+
**Response:**
72
+
73
+
```json
74
+
{
75
+
"jsonrpc": "2.0",
76
+
"id": 1,
77
+
"result": {
78
+
"tools": [
79
+
{
80
+
"name": "get_weather",
81
+
"description": "Get current weather information for a location",
82
+
"inputSchema": {
83
+
"type": "object",
84
+
"properties": {
85
+
"location": {
86
+
"type": "string",
87
+
"description": "City name or zip code"
88
+
}
89
+
},
90
+
"required": ["location"]
91
+
}
92
+
}
93
+
],
94
+
"nextCursor": "next-page-cursor"
95
+
}
96
+
}
97
+
```
98
+
99
+
### Calling Tools
100
+
101
+
To invoke a tool, clients send a `tools/call` request:
102
+
103
+
**Request:**
104
+
105
+
```json
106
+
{
107
+
"jsonrpc": "2.0",
108
+
"id": 2,
109
+
"method": "tools/call",
110
+
"params": {
111
+
"name": "get_weather",
112
+
"arguments": {
113
+
"location": "New York"
114
+
}
115
+
}
116
+
}
117
+
```
118
+
119
+
**Response:**
120
+
121
+
```json
122
+
{
123
+
"jsonrpc": "2.0",
124
+
"id": 2,
125
+
"result": {
126
+
"content": [
127
+
{
128
+
"type": "text",
129
+
"text": "Current weather in New York:\nTemperature: 72°F\nConditions: Partly cloudy"
130
+
}
131
+
],
132
+
"isError": false
133
+
}
134
+
}
135
+
```
136
+
137
+
### List Changed Notification
138
+
139
+
When the list of available tools changes, servers that declared the `listChanged`
140
+
capability **SHOULD** send a notification:
141
+
142
+
```json
143
+
{
144
+
"jsonrpc": "2.0",
145
+
"method": "notifications/tools/list_changed"
146
+
}
147
+
```
148
+
149
+
## Message Flow
150
+
151
+
```mermaid
152
+
sequenceDiagram
153
+
participant LLM
154
+
participant Client
155
+
participant Server
156
+
157
+
Note over Client,Server: Discovery
158
+
Client->>Server: tools/list
159
+
Server-->>Client: List of tools
160
+
161
+
Note over Client,LLM: Tool Selection
162
+
LLM->>Client: Select tool to use
163
+
164
+
Note over Client,Server: Invocation
165
+
Client->>Server: tools/call
166
+
Server-->>Client: Tool result
167
+
Client->>LLM: Process result
168
+
169
+
Note over Client,Server: Updates
170
+
Server--)Client: tools/list_changed
171
+
Client->>Server: tools/list
172
+
Server-->>Client: Updated tools
173
+
```
174
+
175
+
## Data Types
176
+
177
+
### Tool
178
+
179
+
A tool definition includes:
180
+
181
+
- `name`: Unique identifier for the tool
182
+
- `description`: Human-readable description of functionality
183
+
- `inputSchema`: JSON Schema defining expected parameters
184
+
- `annotations`: optional properties describing tool behavior
185
+
186
+
{{< callout type="warning" >}} For trust & safety and security, clients **MUST** consider
187
+
tool annotations to be untrusted unless they come from trusted servers. {{< /callout >}}
188
+
189
+
### Tool Result
190
+
191
+
Tool results can contain multiple content items of different types:
192
+
193
+
#### Text Content
194
+
195
+
```json
196
+
{
197
+
"type": "text",
198
+
"text": "Tool result text"
199
+
}
200
+
```
201
+
202
+
#### Image Content
203
+
204
+
```json
205
+
{
206
+
"type": "image",
207
+
"data": "base64-encoded-data",
208
+
"mimeType": "image/png"
209
+
}
210
+
```
211
+
212
+
#### Audio Content
213
+
214
+
```json
215
+
{
216
+
"type": "audio",
217
+
"data": "base64-encoded-audio-data",
218
+
"mimeType": "audio/wav"
219
+
}
220
+
```
221
+
222
+
#### Embedded Resources
223
+
224
+
[Resources]({{< ref "resources" >}}) **MAY** be embedded, to provide additional context
225
+
or data, behind a URI that can be subscribed to or fetched again by the client later:
226
+
227
+
```json
228
+
{
229
+
"type": "resource",
230
+
"resource": {
231
+
"uri": "resource://example",
232
+
"mimeType": "text/plain",
233
+
"text": "Resource content"
234
+
}
235
+
}
236
+
```
237
+
238
+
## Error Handling
239
+
240
+
Tools use two error reporting mechanisms:
241
+
242
+
1. **Protocol Errors**: Standard JSON-RPC errors for issues like:
243
+
244
+
- Unknown tools
245
+
- Invalid arguments
246
+
- Server errors
247
+
248
+
2. **Tool Execution Errors**: Reported in tool results with `isError: true`:
249
+
- API failures
250
+
- Invalid input data
251
+
- Business logic errors
252
+
253
+
Example protocol error:
254
+
255
+
```json
256
+
{
257
+
"jsonrpc": "2.0",
258
+
"id": 3,
259
+
"error": {
260
+
"code": -32602,
261
+
"message": "Unknown tool: invalid_tool_name"
262
+
}
263
+
}
264
+
```
265
+
266
+
Example tool execution error:
267
+
268
+
```json
269
+
{
270
+
"jsonrpc": "2.0",
271
+
"id": 4,
272
+
"result": {
273
+
"content": [
274
+
{
275
+
"type": "text",
276
+
"text": "Failed to fetch weather data: API rate limit exceeded"
277
+
}
278
+
],
279
+
"isError": true
280
+
}
281
+
}
282
+
```
283
+
284
+
## Security Considerations
285
+
286
+
1. Servers **MUST**:
287
+
288
+
- Validate all tool inputs
289
+
- Implement proper access controls
290
+
- Rate limit tool invocations
291
+
- Sanitize tool outputs
292
+
293
+
2. Clients **SHOULD**:
294
+
- Prompt for user confirmation on sensitive operations
295
+
- Show tool inputs to the user before calling the server, to avoid malicious or
296
+
accidental data exfiltration
297
+
- Validate tool results before passing to LLM
298
+
- Implement timeouts for tool calls
299
+
- Log tool usage for audit purposes
+278
spec/transports.md
+278
spec/transports.md
···
1
+
---
2
+
title: Transports
3
+
type: docs
4
+
weight: 10
5
+
---
6
+
7
+
{{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}}
8
+
9
+
MCP uses JSON-RPC to encode messages. JSON-RPC messages **MUST** be UTF-8 encoded.
10
+
11
+
The protocol currently defines two standard transport mechanisms for client-server
12
+
communication:
13
+
14
+
1. [stdio](#stdio), communication over standard in and standard out
15
+
2. [Streamable HTTP](#streamable-http)
16
+
17
+
Clients **SHOULD** support stdio whenever possible.
18
+
19
+
It is also possible for clients and servers to implement
20
+
[custom transports](#custom-transports) in a pluggable fashion.
21
+
22
+
## stdio
23
+
24
+
In the **stdio** transport:
25
+
26
+
- The client launches the MCP server as a subprocess.
27
+
- The server reads JSON-RPC messages from its standard input (`stdin`) and sends messages
28
+
to its standard output (`stdout`).
29
+
- Messages may be JSON-RPC requests, notifications, responses—or a JSON-RPC
30
+
[batch](https://www.jsonrpc.org/specification#batch) containing one or more requests
31
+
and/or notifications.
32
+
- Messages are delimited by newlines, and **MUST NOT** contain embedded newlines.
33
+
- The server **MAY** write UTF-8 strings to its standard error (`stderr`) for logging
34
+
purposes. Clients **MAY** capture, forward, or ignore this logging.
35
+
- The server **MUST NOT** write anything to its `stdout` that is not a valid MCP message.
36
+
- The client **MUST NOT** write anything to the server's `stdin` that is not a valid MCP
37
+
message.
38
+
39
+
```mermaid
40
+
sequenceDiagram
41
+
participant Client
42
+
participant Server Process
43
+
44
+
Client->>+Server Process: Launch subprocess
45
+
loop Message Exchange
46
+
Client->>Server Process: Write to stdin
47
+
Server Process->>Client: Write to stdout
48
+
Server Process--)Client: Optional logs on stderr
49
+
end
50
+
Client->>Server Process: Close stdin, terminate subprocess
51
+
deactivate Server Process
52
+
```
53
+
54
+
## Streamable HTTP
55
+
56
+
{{< callout type="info" >}} This replaces the [HTTP+SSE
57
+
transport]({{< ref "/specification/2024-11-05/basic/transports#http-with-sse" >}}) from
58
+
protocol version 2024-11-05. See the [backwards compatibility](#backwards-compatibility)
59
+
guide below. {{< /callout >}}
60
+
61
+
In the **Streamable HTTP** transport, the server operates as an independent process that
62
+
can handle multiple client connections. This transport uses HTTP POST and GET requests.
63
+
Server can optionally make use of
64
+
[Server-Sent Events](https://en.wikipedia.org/wiki/Server-sent_events) (SSE) to stream
65
+
multiple server messages. This permits basic MCP servers, as well as more feature-rich
66
+
servers supporting streaming and server-to-client notifications and requests.
67
+
68
+
The server **MUST** provide a single HTTP endpoint path (hereafter referred to as the
69
+
**MCP endpoint**) that supports both POST and GET methods. For example, this could be a
70
+
URL like `https://example.com/mcp`.
71
+
72
+
### Sending Messages to the Server
73
+
74
+
Every JSON-RPC message sent from the client **MUST** be a new HTTP POST request to the
75
+
MCP endpoint.
76
+
77
+
1. The client **MUST** use HTTP POST to send JSON-RPC messages to the MCP endpoint.
78
+
2. The client **MUST** include an `Accept` header, listing both `application/json` and
79
+
`text/event-stream` as supported content types.
80
+
3. The body of the POST request **MUST** be one of the following:
81
+
- A single JSON-RPC _request_, _notification_, or _response_
82
+
- An array [batching](https://www.jsonrpc.org/specification#batch) one or more
83
+
_requests and/or notifications_
84
+
- An array [batching](https://www.jsonrpc.org/specification#batch) one or more
85
+
_responses_
86
+
4. If the input consists solely of (any number of) JSON-RPC _responses_ or
87
+
_notifications_:
88
+
- If the server accepts the input, the server **MUST** return HTTP status code 202
89
+
Accepted with no body.
90
+
- If the server cannot accept the input, it **MUST** return an HTTP error status code
91
+
(e.g., 400 Bad Request). The HTTP response body **MAY** comprise a JSON-RPC _error
92
+
response_ that has no `id`.
93
+
5. If the input contains any number of JSON-RPC _requests_, the server **MUST** either
94
+
return `Content-Type: text/event-stream`, to initiate an SSE stream, or
95
+
`Content-Type: application/json`, to return one JSON object. The client **MUST**
96
+
support both these cases.
97
+
6. If the server initiates an SSE stream:
98
+
- The SSE stream **SHOULD** eventually include one JSON-RPC _response_ per each
99
+
JSON-RPC _request_ sent in the POST body. These _responses_ **MAY** be
100
+
[batched](https://www.jsonrpc.org/specification#batch).
101
+
- The server **MAY** send JSON-RPC _requests_ and _notifications_ before sending a
102
+
JSON-RPC _response_. These messages **SHOULD** relate to the originating client
103
+
_request_. These _requests_ and _notifications_ **MAY** be
104
+
[batched](https://www.jsonrpc.org/specification#batch).
105
+
- The server **SHOULD NOT** close the SSE stream before sending a JSON-RPC _response_
106
+
per each received JSON-RPC _request_, unless the [session](#session-management)
107
+
expires.
108
+
- After all JSON-RPC _responses_ have been sent, the server **SHOULD** close the SSE
109
+
stream.
110
+
- Disconnection **MAY** occur at any time (e.g., due to network conditions).
111
+
Therefore:
112
+
- Disconnection **SHOULD NOT** be interpreted as the client cancelling its request.
113
+
- To cancel, the client **SHOULD** explicitly send an MCP `CancelledNotification`.
114
+
- To avoid message loss due to disconnection, the server **MAY** make the stream
115
+
[resumable](#resumability-and-redelivery).
116
+
117
+
### Listening for Messages from the Server
118
+
119
+
1. The client **MAY** issue an HTTP GET to the MCP endpoint. This can be used to open an
120
+
SSE stream, allowing the server to communicate to the client, without the client first
121
+
sending data via HTTP POST.
122
+
2. The client **MUST** include an `Accept` header, listing `text/event-stream` as a
123
+
supported content type.
124
+
3. The server **MUST** either return `Content-Type: text/event-stream` in response to
125
+
this HTTP GET, or else return HTTP 405 Method Not Allowed, indicating that the server
126
+
does not offer an SSE stream at this endpoint.
127
+
4. If the server initiates an SSE stream:
128
+
- The server **MAY** send JSON-RPC _requests_ and _notifications_ on the stream. These
129
+
_requests_ and _notifications_ **MAY** be
130
+
[batched](https://www.jsonrpc.org/specification#batch).
131
+
- These messages **SHOULD** be unrelated to any concurrently-running JSON-RPC
132
+
_request_ from the client.
133
+
- The server **MUST NOT** send a JSON-RPC _response_ on the stream **unless**
134
+
[resuming](#resumability-and-redelivery) a stream associated with a previous client
135
+
request.
136
+
- The server **MAY** close the SSE stream at any time.
137
+
- The client **MAY** close the SSE stream at any time.
138
+
139
+
### Multiple Connections
140
+
141
+
1. The client **MAY** remain connected to multiple SSE streams simultaneously.
142
+
2. The server **MUST** send each of its JSON-RPC messages on only one of the connected
143
+
streams; that is, it **MUST NOT** broadcast the same message across multiple streams.
144
+
- The risk of message loss **MAY** be mitigated by making the stream
145
+
[resumable](#resumability-and-redelivery).
146
+
147
+
### Resumability and Redelivery
148
+
149
+
To support resuming broken connections, and redelivering messages that might otherwise be
150
+
lost:
151
+
152
+
1. Servers **MAY** attach an `id` field to their SSE events, as described in the
153
+
[SSE standard](https://html.spec.whatwg.org/multipage/server-sent-events.html#event-stream-interpretation).
154
+
- If present, the ID **MUST** be globally unique across all streams within that
155
+
[session](#session-management)—or all streams with that specific client, if session
156
+
management is not in use.
157
+
2. If the client wishes to resume after a broken connection, it **SHOULD** issue an HTTP
158
+
GET to the MCP endpoint, and include the
159
+
[`Last-Event-ID`](https://html.spec.whatwg.org/multipage/server-sent-events.html#the-last-event-id-header)
160
+
header to indicate the last event ID it received.
161
+
- The server **MAY** use this header to replay messages that would have been sent
162
+
after the last event ID, _on the stream that was disconnected_, and to resume the
163
+
stream from that point.
164
+
- The server **MUST NOT** replay messages that would have been delivered on a
165
+
different stream.
166
+
167
+
In other words, these event IDs should be assigned by servers on a _per-stream_ basis, to
168
+
act as a cursor within that particular stream.
169
+
170
+
### Session Management
171
+
172
+
An MCP "session" consists of logically related interactions between a client and a
173
+
server, beginning with the [initialization phase]({{< ref "lifecycle" >}}). To support
174
+
servers which want to establish stateful sessions:
175
+
176
+
1. A server using the Streamable HTTP transport **MAY** assign a session ID at
177
+
initialization time, by including it in an `Mcp-Session-Id` header on the HTTP
178
+
response containing the `InitializeResult`.
179
+
- The session ID **SHOULD** be globally unique and cryptographically secure (e.g., a
180
+
securely generated UUID, a JWT, or a cryptographic hash).
181
+
- The session ID **MUST** only contain visible ASCII characters (ranging from 0x21 to
182
+
0x7E).
183
+
2. If an `Mcp-Session-Id` is returned by the server during initialization, clients using
184
+
the Streamable HTTP transport **MUST** include it in the `Mcp-Session-Id` header on
185
+
all of their subsequent HTTP requests.
186
+
- Servers that require a session ID **SHOULD** respond to requests without an
187
+
`Mcp-Session-Id` header (other than initialization) with HTTP 400 Bad Request.
188
+
3. The server **MAY** terminate the session at any time, after which it **MUST** respond
189
+
to requests containing that session ID with HTTP 404 Not Found.
190
+
4. When a client receives HTTP 404 in response to a request containing an
191
+
`Mcp-Session-Id`, it **MUST** start a new session by sending a new `InitializeRequest`
192
+
without a session ID attached.
193
+
5. Clients that no longer need a particular session (e.g., because the user is leaving
194
+
the client application) **SHOULD** send an HTTP DELETE to the MCP endpoint with the
195
+
`Mcp-Session-Id` header, to explicitly terminate the session.
196
+
- The server **MAY** respond to this request with HTTP 405 Method Not Allowed,
197
+
indicating that the server does not allow clients to terminate sessions.
198
+
199
+
### Sequence Diagram
200
+
201
+
```mermaid
202
+
sequenceDiagram
203
+
participant Client
204
+
participant Server
205
+
206
+
note over Client, Server: initialization
207
+
208
+
Client->>+Server: POST InitializeRequest
209
+
Server->>-Client: InitializeResponse<br>Mcp-Session-Id: 1868a90c...
210
+
211
+
Client->>+Server: POST InitializedNotification<br>Mcp-Session-Id: 1868a90c...
212
+
Server->>-Client: 202 Accepted
213
+
214
+
note over Client, Server: client requests
215
+
Client->>+Server: POST ... request ...<br>Mcp-Session-Id: 1868a90c...
216
+
217
+
alt single HTTP response
218
+
Server->>Client: ... response ...
219
+
else server opens SSE stream
220
+
loop while connection remains open
221
+
Server-)Client: ... SSE messages from server ...
222
+
end
223
+
Server-)Client: SSE event: ... response ...
224
+
end
225
+
deactivate Server
226
+
227
+
note over Client, Server: client notifications/responses
228
+
Client->>+Server: POST ... notification/response ...<br>Mcp-Session-Id: 1868a90c...
229
+
Server->>-Client: 202 Accepted
230
+
231
+
note over Client, Server: server requests
232
+
Client->>+Server: GET<br>Mcp-Session-Id: 1868a90c...
233
+
loop while connection remains open
234
+
Server-)Client: ... SSE messages from server ...
235
+
end
236
+
deactivate Server
237
+
238
+
```
239
+
240
+
### Backwards Compatibility
241
+
242
+
Clients and servers can maintain backwards compatibility with the deprecated [HTTP+SSE
243
+
transport]({{< ref "/specification/2024-11-05/basic/transports#http-with-sse" >}}) (from
244
+
protocol version 2024-11-05) as follows:
245
+
246
+
**Servers** wanting to support older clients should:
247
+
248
+
- Continue to host both the SSE and POST endpoints of the old transport, alongside the
249
+
new "MCP endpoint" defined for the Streamable HTTP transport.
250
+
- It is also possible to combine the old POST endpoint and the new MCP endpoint, but
251
+
this may introduce unneeded complexity.
252
+
253
+
**Clients** wanting to support older servers should:
254
+
255
+
1. Accept an MCP server URL from the user, which may point to either a server using the
256
+
old transport or the new transport.
257
+
2. Attempt to POST an `InitializeRequest` to the server URL, with an `Accept` header as
258
+
defined above:
259
+
- If it succeeds, the client can assume this is a server supporting the new Streamable
260
+
HTTP transport.
261
+
- If it fails with an HTTP 4xx status code (e.g., 405 Method Not Allowed or 404 Not
262
+
Found):
263
+
- Issue a GET request to the server URL, expecting that this will open an SSE stream
264
+
and return an `endpoint` event as the first event.
265
+
- When the `endpoint` event arrives, the client can assume this is a server running
266
+
the old HTTP+SSE transport, and should use that transport for all subsequent
267
+
communication.
268
+
269
+
## Custom Transports
270
+
271
+
Clients and servers **MAY** implement additional custom transport mechanisms to suit
272
+
their specific needs. The protocol is transport-agnostic and can be implemented over any
273
+
communication channel that supports bidirectional message exchange.
274
+
275
+
Implementers who choose to support custom transports **MUST** ensure they preserve the
276
+
JSON-RPC message format and lifecycle requirements defined by MCP. Custom transports
277
+
**SHOULD** document their specific connection establishment and message exchange patterns
278
+
to aid interoperability.