Skip to content

Commit 66a1cdd

Browse files
jspahrsummersjspahrsummers
committed
Fix formatting
1 parent fb8e9ce commit 66a1cdd

File tree

3 files changed

+97
-45
lines changed

3 files changed

+97
-45
lines changed

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -120,8 +120,8 @@ For example: `MCP-Protocol-Version: 2024-11-05`
120120

121121
#### 2.3.2 Authorization Base URL
122122

123-
The authorization base URL **MUST** be determined from the MCP server URL by
124-
discarding any existing `path` component. For example:
123+
The authorization base URL **MUST** be determined from the MCP server URL by discarding
124+
any existing `path` component. For example:
125125

126126
If the MCP server URL is `https://api.example.com/v1/mcp`, then:
127127

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -55,8 +55,8 @@ Responses are sent in reply to requests.
5555

5656
## Notifications
5757

58-
Notifications are sent from the client to the server or vice versa. The receiver **MUST NOT**
59-
send a response.
58+
Notifications are sent from the client to the server or vice versa. The receiver **MUST
59+
NOT** send a response.
6060

6161
```typescript
6262
{

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

Lines changed: 93 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -50,73 +50,112 @@ sequenceDiagram
5050

5151
## Streamable HTTP
5252

53-
{{< callout type="info" >}} This replaces the [HTTP+SSE transport]({{< ref "/specification/2024-11-05/basic/transports#http-with-sse" >}}) from protocol version 2024-11-05. See the [backwards compatibility](#backwards-compatibility) guide below. {{< /callout >}}
53+
{{< callout type="info" >}} This replaces the [HTTP+SSE
54+
transport]({{< ref "/specification/2024-11-05/basic/transports#http-with-sse" >}}) from
55+
protocol version 2024-11-05. See the [backwards compatibility](#backwards-compatibility)
56+
guide below. {{< /callout >}}
5457

55-
In the **Streamable HTTP** transport, the server operates as an independent process that can handle multiple client connections. This transport uses standard HTTP with optional [Server-Sent Events](https://en.wikipedia.org/wiki/Server-sent_events) (SSE) for streaming multiple server messages. This permits "plain HTTP" MCP servers, as well as more feature-rich servers supporting streaming and bidirectional communication.
58+
In the **Streamable HTTP** transport, the server operates as an independent process that
59+
can handle multiple client connections. This transport uses standard HTTP with optional
60+
[Server-Sent Events](https://en.wikipedia.org/wiki/Server-sent_events) (SSE) for
61+
streaming multiple server messages. This permits "plain HTTP" MCP servers, as well as
62+
more feature-rich servers supporting streaming and bidirectional communication.
5663

57-
The server **MUST** provide a single HTTP endpoint (hereafter referred to as the **MCP endpoint**) that supports both POST and GET methods. For example, this could be a URL like `https://example.com/mcp`.
64+
The server **MUST** provide a single HTTP endpoint (hereafter referred to as the **MCP
65+
endpoint**) that supports both POST and GET methods. For example, this could be a URL
66+
like `https://example.com/mcp`.
5867

5968
### Message Exchange
6069

61-
1. Every JSON-RPC message sent from the client **MUST** be a new HTTP POST request to the MCP endpoint.
70+
1. Every JSON-RPC message sent from the client **MUST** be a new HTTP POST request to the
71+
MCP endpoint.
6272

6373
2. When the client sends a JSON-RPC _request_ message to the MCP endpoint via POST:
64-
- The client **MUST** include an `Accept` header, listing both `application/json` and `text/event-stream` as supported content types.
65-
- The server **MUST** either return `Content-Type: text/event-stream`, to initiate an SSE stream, or `Content-Type: application/json`, to return a single JSON-RPC _response_. The client **MUST** support both these cases.
74+
75+
- The client **MUST** include an `Accept` header, listing both `application/json` and
76+
`text/event-stream` as supported content types.
77+
- The server **MUST** either return `Content-Type: text/event-stream`, to initiate an
78+
SSE stream, or `Content-Type: application/json`, to return a single JSON-RPC
79+
_response_. The client **MUST** support both these cases.
6680
- If the server initiates an SSE stream:
6781
- The SSE stream **SHOULD** eventually include a JSON-RPC _response_ message.
68-
- The server **MAY** send JSON-RPC _requests_ and JSON-RPC _notifications_ before sending a JSON-RPC _response_.
69-
- The server **SHOULD NOT** close the SSE stream before sending the JSON-RPC _response_.
70-
- After the JSON-RPC _response_ has been sent, the server **MAY** close the SSE stream at any time.
71-
- The client **MAY** close the SSE stream at any time. The server **SHOULD** interpret this as the client cancelling the request, if it is still in-flight.
72-
73-
3. When the client sends a JSON-RPC _notification_ or _response_ to the MCP endpoint via POST:
74-
- The client **MUST** include an `Accept` header, listing `text/event-stream` as a supported content type.
75-
- The server **MUST** either return `Content-Type: text/event-stream`, to initiate an SSE stream, or else HTTP status code 202 Accepted with no body. The client **MUST** support both these cases.
82+
- The server **MAY** send JSON-RPC _requests_ and JSON-RPC _notifications_ before
83+
sending a JSON-RPC _response_.
84+
- The server **SHOULD NOT** close the SSE stream before sending the JSON-RPC
85+
_response_.
86+
- After the JSON-RPC _response_ has been sent, the server **MAY** close the SSE
87+
stream at any time.
88+
- The client **MAY** close the SSE stream at any time. The server **SHOULD**
89+
interpret this as the client cancelling the request, if it is still in-flight.
90+
91+
3. When the client sends a JSON-RPC _notification_ or _response_ to the MCP endpoint via
92+
POST:
93+
94+
- The client **MUST** include an `Accept` header, listing `text/event-stream` as a
95+
supported content type.
96+
- The server **MUST** either return `Content-Type: text/event-stream`, to initiate an
97+
SSE stream, or else HTTP status code 202 Accepted with no body. The client **MUST**
98+
support both these cases.
7699
- If the server initiates an SSE stream:
77-
- The receipt of the message is acknowledged as soon as the HTTP status code is received (before the SSE stream begins).
100+
- The receipt of the message is acknowledged as soon as the HTTP status code is
101+
received (before the SSE stream begins).
78102
- The server **MAY** close the SSE stream at any time.
79103
- The client **MAY** close the SSE stream at any time.
80104

81-
4. The client **MAY** also issue an HTTP GET to the MCP endpoint. This can be used to open an SSE stream (allowing the server to communicate to the client) without having first sent a _request_, _notification_, or _response_.
82-
- The client **MUST** include an `Accept` header, listing `text/event-stream` as a supported content type.
83-
- The server **MUST** either return `Content-Type: text/event-stream` in response to this HTTP GET, or else HTTP status code 204 No Content with no body. The client **MUST** support both these cases.
105+
4. The client **MAY** also issue an HTTP GET to the MCP endpoint. This can be used to
106+
open an SSE stream (allowing the server to communicate to the client) without having
107+
first sent a _request_, _notification_, or _response_.
108+
- The client **MUST** include an `Accept` header, listing `text/event-stream` as a
109+
supported content type.
110+
- The server **MUST** either return `Content-Type: text/event-stream` in response to
111+
this HTTP GET, or else HTTP status code 204 No Content with no body. The client
112+
**MUST** support both these cases.
84113
- If the server initiates an SSE stream:
85114
- The server **MAY** close the SSE stream at any time.
86115
- The client **MAY** close the SSE stream at any time.
87116

88117
### Session Management
89118

90-
Where a client desires to share a single logical session across multiple requests, it **MAY** attach an `Mcp-Session-Id` HTTP header to its requests. This permits resumability and maintenance of session state across separate POSTs.
119+
Where a client desires to share a single logical session across multiple requests, it
120+
**MAY** attach an `Mcp-Session-Id` HTTP header to its requests. This permits resumability
121+
and maintenance of session state across separate POSTs.
91122

92123
1. It is the client's responsibility to generate or select the session ID.
93-
2. This session ID **SHOULD** be globally unique and cryptographically secure (e.g., a UUID or a JWT), unless it is specifically desired to share a session ID across users or clients.
124+
2. This session ID **SHOULD** be globally unique and cryptographically secure (e.g., a
125+
UUID or a JWT), unless it is specifically desired to share a session ID across users
126+
or clients.
94127
3. The server **MAY** use this header to associate state with the logical session.
95-
4. If [authorization]({{< ref "authorization" >}}) is used _and_ the server makes use of the `Mcp-Session-Id` header:
96-
- The server **SHOULD** bind the session ID to the authorization context, and return an error if the session ID is reused in a different authorization context.
128+
4. If [authorization]({{< ref "authorization" >}}) is used _and_ the server makes use of
129+
the `Mcp-Session-Id` header:
130+
- The server **SHOULD** bind the session ID to the authorization context, and return
131+
an error if the session ID is reused in a different authorization context.
97132

98133
### Multiple Connections
99134

100135
1. The client **MAY** remain connected to multiple SSE streams simultaneously.
101-
2. The server **MAY** broadcast its JSON-RPC messages on all connected SSE streams, or it **MAY** limit its communication on any particular stream only to messages related to the client's original request on that stream.
102-
- The client **MUST** ignore duplicate _requests_ and _responses_ received in this way, by ignoring any duplicate JSON-RPC request IDs in either.
103-
- The client **MUST** be resilient to duplicate _notifications_, handling them with idempotency.
136+
2. The server **MAY** broadcast its JSON-RPC messages on all connected SSE streams, or it
137+
**MAY** limit its communication on any particular stream only to messages related to
138+
the client's original request on that stream.
139+
- The client **MUST** ignore duplicate _requests_ and _responses_ received in this
140+
way, by ignoring any duplicate JSON-RPC request IDs in either.
141+
- The client **MUST** be resilient to duplicate _notifications_, handling them with
142+
idempotency.
104143

105144
### Sequence Diagram
106145

107146
```mermaid
108147
sequenceDiagram
109148
participant Client
110149
participant Server
111-
150+
112151
note over Client, Server: initialization
113152
114153
Client->>+Server: POST InitializeRequest<br>Mcp-Session-Id: foo
115154
Server->>Client: InitializeResponse
116155
deactivate Server
117-
156+
118157
Client->>+Server: POST InitializedNotification<br>Mcp-Session-Id: foo
119-
158+
120159
alt single HTTP response
121160
Server->>Client: 202 Accepted
122161
else server opens SSE stream
@@ -126,11 +165,11 @@ sequenceDiagram
126165
Client-->Server: (client or server MAY disconnect)
127166
end
128167
deactivate Server
129-
168+
130169
note over Client, Server: normal operation (sequentially or concurrently)
131-
170+
132171
Client->>+Server: POST ... other messages ...<br>Mcp-Session-Id: foo
133-
172+
134173
alt single HTTP response
135174
Server->>Client: ... response ...
136175
else server opens SSE stream
@@ -141,25 +180,38 @@ sequenceDiagram
141180
Server-)Client: SSE event: (response)
142181
end
143182
end
144-
183+
145184
deactivate Server
146185
```
147186

148187
### Backwards Compatibility
149188

150-
Clients and servers can maintain backwards compatibility with the deprecated [HTTP+SSE transport]({{< ref "/specification/2024-11-05/basic/transports#http-with-sse" >}}) (from protocol version 2024-11-05) as follows:
189+
Clients and servers can maintain backwards compatibility with the deprecated [HTTP+SSE
190+
transport]({{< ref "/specification/2024-11-05/basic/transports#http-with-sse" >}}) (from
191+
protocol version 2024-11-05) as follows:
151192

152193
**Servers** wanting to support older clients should:
153-
- Continue to host both the SSE and POST endpoints of the old transport, alongside the new "MCP endpoint" defined for the Streamable HTTP transport.
154-
- It is also possible to combine the old POST endpoint and the new MCP endpoint, but this may introduce unneeded complexity.
194+
195+
- Continue to host both the SSE and POST endpoints of the old transport, alongside the
196+
new "MCP endpoint" defined for the Streamable HTTP transport.
197+
- It is also possible to combine the old POST endpoint and the new MCP endpoint, but
198+
this may introduce unneeded complexity.
155199

156200
**Clients** wanting to support older servers should:
157-
1. Accept an MCP server URL from the user, which may point to either a server using the old transport or the new transport.
158-
2. Attempt to POST an `InitializeRequest` to the server URL, with an `Accept` header as defined above:
159-
- If it succeeds or opens an SSE stream in response, the client can assume this is a server supporting the new Streamable HTTP transport.
160-
- If it fails with an HTTP 4xx status code (e.g., 405 Method Not Allowed or 404 Not Found):
161-
- Issue a GET request to the server URL, expecting that this will open an SSE stream and return an `endpoint` event as the first event.
162-
- When the `endpoint` event arrives, the client can assume this is a server running the old HTTP+SSE transport, and should use that transport for all subsequent communication.
201+
202+
1. Accept an MCP server URL from the user, which may point to either a server using the
203+
old transport or the new transport.
204+
2. Attempt to POST an `InitializeRequest` to the server URL, with an `Accept` header as
205+
defined above:
206+
- If it succeeds or opens an SSE stream in response, the client can assume this is a
207+
server supporting the new Streamable HTTP transport.
208+
- If it fails with an HTTP 4xx status code (e.g., 405 Method Not Allowed or 404 Not
209+
Found):
210+
- Issue a GET request to the server URL, expecting that this will open an SSE stream
211+
and return an `endpoint` event as the first event.
212+
- When the `endpoint` event arrives, the client can assume this is a server running
213+
the old HTTP+SSE transport, and should use that transport for all subsequent
214+
communication.
163215

164216
## Custom Transports
165217

0 commit comments

Comments
 (0)