Skip to content

Commit 1de5822

Browse files
jspahrsummersjspahrsummers
committed
Update Streamable HTTP transport to account for batching
1 parent fc5fc3d commit 1de5822

File tree

1 file changed

+62
-53
lines changed

1 file changed

+62
-53
lines changed

‎docs/specification/draft/basic/transports.md‎

Lines changed: 62 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -68,59 +68,68 @@ URL like `https://example.com/mcp`.
6868

6969
### Message Exchange
7070

71-
1. Every JSON-RPC message sent from the client **MUST** be a new HTTP POST request to the
72-
MCP endpoint.
73-
74-
2. When the client sends a JSON-RPC _request_ to the MCP endpoint via POST:
75-
76-
- The client **MUST** include an `Accept` header, listing both `application/json` and
77-
`text/event-stream` as supported content types.
78-
- The server **MUST** either return `Content-Type: text/event-stream`, to initiate an
79-
SSE stream, or `Content-Type: application/json`, to return a single JSON-RPC
80-
_response_. The client **MUST** support both these cases.
81-
- If the server initiates an SSE stream:
82-
- The SSE stream **SHOULD** eventually include a JSON-RPC _response_ message.
83-
- The server **MAY** send JSON-RPC _requests_ and _notifications_ before sending a
84-
JSON-RPC _response_. These messages **SHOULD** relate to the originating client
85-
_request_.
86-
- The server **SHOULD NOT** close the SSE stream before sending the JSON-RPC
87-
_response_, unless the [session](#session-management) expires.
88-
- After the JSON-RPC _response_ has been sent, the server **MAY** close the SSE
89-
stream at any time.
90-
- Disconnection **MAY** occur at any time (e.g., due to network conditions).
91-
Therefore:
92-
- Disconnection **SHOULD NOT** be interpreted as the client cancelling its
93-
request.
94-
- To cancel, the client **SHOULD** explicitly send an MCP `CancelledNotification`.
95-
- To avoid message loss due to disconnection, the server **MAY** make the stream
96-
[resumable](#resumability-and-redelivery).
97-
98-
3. When the client sends a JSON-RPC _notification_ or _response_ to the MCP endpoint via
99-
POST:
100-
101-
- If the server accepts the message, it **MUST** return HTTP status code 202 Accepted
102-
with no body.
103-
- If the server cannot accept the message, it **MUST** return an HTTP error status
104-
code (e.g., 400 Bad Request). The HTTP response body **MAY** comprise a JSON-RPC
105-
_error response_ that has no `id`.
106-
107-
4. The client **MAY** also issue an HTTP GET to the MCP endpoint. This can be used to
108-
open an SSE stream, allowing the server to communicate to the client without the
109-
client first sending a JSON-RPC _request_.
110-
- The client **MUST** include an `Accept` header, listing `text/event-stream` as a
111-
supported content type.
112-
- The server **MUST** either return `Content-Type: text/event-stream` in response to
113-
this HTTP GET, or else return HTTP 405 Method Not Allowed, indicating that the
114-
server does not offer an SSE stream at this endpoint.
115-
- If the server initiates an SSE stream:
116-
- The server **MAY** send JSON-RPC _requests_ and _notifications_ on the stream.
117-
These messages **SHOULD** be unrelated to any concurrently-running JSON-RPC
118-
_request_ from the client.
119-
- The server **MUST NOT** send a JSON-RPC _response_ on the stream **unless**
120-
[resuming](#resumability-and-redelivery) a stream associated with a previous
121-
client request.
122-
- The server **MAY** close the SSE stream at any time.
123-
- The client **MAY** close the SSE stream at any time.
71+
Every JSON-RPC message sent from the client **MUST** be a new HTTP POST request to the
72+
MCP endpoint.
73+
74+
#### Sending Messages to the Server
75+
76+
1. The client **MUST** use HTTP POST to send JSON-RPC messages to the MCP endpoint.
77+
2. The client **MUST** include an `Accept` header, listing both `application/json` and
78+
`text/event-stream` as supported content types.
79+
3. The body of the POST request **MUST** be a single JSON-RPC _request_, _notification_,
80+
or _response_—or a [JSON-RPC _batch_](https://www.jsonrpc.org/specification#batch)
81+
containing one or more _requests and/or notifications_.
82+
4. If the input consists solely of one JSON-RPC _response_ or any number of JSON-RPC
83+
_notifications_:
84+
- If the server accepts the input, the server **MUST** return HTTP status code 202
85+
Accepted with no body.
86+
- If the server cannot accept the input, it **MUST** return an HTTP error status code
87+
(e.g., 400 Bad Request). The HTTP response body **MAY** comprise a JSON-RPC _error
88+
response_ that has no `id`.
89+
5. If the input contains any number of JSON-RPC _requests_, the server **MUST** either
90+
return `Content-Type: text/event-stream`, to initiate an SSE stream, or
91+
`Content-Type: application/json`, to return one JSON object. The client **MUST**
92+
support both these cases.
93+
6. If the server initiates an SSE stream:
94+
- The SSE stream **SHOULD** eventually include one JSON-RPC _response_ per each
95+
JSON-RPC _request_ sent in the POST body.
96+
- The server **MAY** send JSON-RPC _requests_ and _notifications_ before sending a
97+
JSON-RPC _response_. These messages **SHOULD** relate to the originating client
98+
_request_. These _requests_ and _notifications_ **MAY** be
99+
[batched](https://www.jsonrpc.org/specification#batch).
100+
- The server **SHOULD NOT** close the SSE stream before sending a JSON-RPC _response_
101+
per each received JSON-RPC _request_, unless the [session](#session-management)
102+
expires.
103+
- After all JSON-RPC _responses_ have been sent, the server **SHOULD** close the SSE
104+
stream.
105+
- Disconnection **MAY** occur at any time (e.g., due to network conditions).
106+
Therefore:
107+
- Disconnection **SHOULD NOT** be interpreted as the client cancelling its request.
108+
- To cancel, the client **SHOULD** explicitly send an MCP `CancelledNotification`.
109+
- To avoid message loss due to disconnection, the server **MAY** make the stream
110+
[resumable](#resumability-and-redelivery).
111+
112+
#### Listening for Messages from the Server
113+
114+
1. The client **MAY** issue an HTTP GET to the MCP endpoint. This can be used to open an
115+
SSE stream, allowing the server to communicate to the client, without the client first
116+
sending data via HTTP POST.
117+
2. The client **MUST** include an `Accept` header, listing `text/event-stream` as a
118+
supported content type.
119+
3. The server **MUST** either return `Content-Type: text/event-stream` in response to
120+
this HTTP GET, or else return HTTP 405 Method Not Allowed, indicating that the server
121+
does not offer an SSE stream at this endpoint.
122+
4. If the server initiates an SSE stream:
123+
- The server **MAY** send JSON-RPC _requests_ and _notifications_ on the stream. These
124+
_requests_ and _notifications_ **MAY** be
125+
[batched](https://www.jsonrpc.org/specification#batch).
126+
- These messages **SHOULD** be unrelated to any concurrently-running JSON-RPC
127+
_request_ from the client.
128+
- The server **MUST NOT** send a JSON-RPC _response_ on the stream **unless**
129+
[resuming](#resumability-and-redelivery) a stream associated with a previous client
130+
request.
131+
- The server **MAY** close the SSE stream at any time.
132+
- The client **MAY** close the SSE stream at any time.
124133

125134
### Multiple Connections
126135

0 commit comments

Comments
 (0)