Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

RFC Stateless #153

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions docs/specification/2024-11-05/architecture/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,8 @@ The Model Context Protocol (MCP) follows a client-host-server architecture where
host can run multiple client instances. This architecture enables users to integrate AI
capabilities across applications while maintaining clear security boundaries and
isolating concerns. Built on JSON-RPC, MCP provides a stateful session protocol focused
on context exchange and sampling coordination between clients and servers.
on context exchange and sampling coordination between clients and servers. A stateless
version of the protocol is available, which provides a subset of the capabiities.

## Core Components

Expand Down Expand Up @@ -61,7 +62,7 @@ The host process acts as the container and coordinator:

Each client is created by the host and maintains an isolated server connection:

- Establishes one stateful session per server
- Establishes one stateful or stateless session per server
- Handles protocol negotiation and capability exchange
- Routes protocol messages bidirectionally
- Manages subscriptions and notifications
Expand Down Expand Up @@ -175,6 +176,8 @@ sequenceDiagram
deactivate Server
```

In case of stateless transport, there will be no "Server Request".

Each capability unlocks specific protocol features for use during the session. For
example:

Expand Down
23 changes: 16 additions & 7 deletions docs/specification/2024-11-05/basic/lifecycle.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,8 +103,8 @@ The server **MUST** respond with its own capabilities and information:
}
```

After successful initialization, the client **MUST** send an `initialized` notification
to indicate it is ready to begin normal operations:
When using _statfull_ transports, after successful initialization, the client **MUST**
pcingola marked this conversation as resolved.
Show resolved Hide resolved
send an `initialized` notification to indicate it is ready to begin normal operations:

```json
{
Expand All @@ -126,9 +126,13 @@ to indicate it is ready to begin normal operations:
In the `initialize` request, the client **MUST** send a protocol version it supports.
This **SHOULD** be the _latest_ version supported by the client.

If the server supports the requested protocol version, it **MUST** respond with the same
version. Otherwise, the server **MUST** respond with another protocol version it
supports. This **SHOULD** be the _latest_ version supported by the server.
For _statfull_ transports, if the server supports the requested protocol version, it
pcingola marked this conversation as resolved.
Show resolved Hide resolved
**MUST** respond with the same version. Otherwise, the server **MUST** respond with
another protocol version it supports. This **SHOULD** be the _latest_ version supported
by the server.

For _stateless_ transports, the server **SHOULD** respond with the _latest_ version
supported by the server.

If the client does not support the version in the server's response, it **SHOULD**
disconnect.
Expand Down Expand Up @@ -186,10 +190,15 @@ client **SHOULD** initiate shutdown by:
The server **MAY** initiate shutdown by closing its output stream to the client and
exiting.

#### SSE

For SSE [transport]({{< ref "/specification/2024-11-05/basic/transports" >}}), shutdown
is indicated by closing the associated SSE connection(s).

#### HTTP

For HTTP [transports]({{< ref "/specification/2024-11-05/basic/transports" >}}), shutdown
is indicated by closing the associated HTTP connection(s).
For HTTP [transport]({{< ref "/specification/2024-11-05/basic/transports" >}}), shutdown
is not needed.

## Error Handling

Expand Down
8 changes: 5 additions & 3 deletions docs/specification/2024-11-05/basic/messages.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,8 @@ three types of messages:

## Requests

Requests are sent from the client to the server or vice versa.
Requests are sent from the client to the server, or vice versa if the transport
qand capabilities allows (e.g. the HTTP transport does not allow server requests).

```typescript
{
Expand Down Expand Up @@ -56,8 +57,9 @@ Responses are sent in reply to requests.

## Notifications

Notifications are sent from the client to the server or vice versa. They do not expect a
response.
Notifications are sent from the client to the server or vice versa if the transport
and capabilities allows (e.g. the HTTP transport does not allow server notifications).
Notifications do not expect a response.

```typescript
{
Expand Down
33 changes: 30 additions & 3 deletions docs/specification/2024-11-05/basic/transports.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,14 @@ weight: 40
{{< callout type="info" >}} **Protocol Revision**: {{< param protocolRevision >}}
{{< /callout >}}

MCP currently defines two standard transport mechanisms for client-server communication:
MCP currently defines three standard transport mechanisms for client-server communication:

1. [stdio](#stdio), communication over standard in and standard out
2. [HTTP with Server-Sent Events](#http-with-sse) (SSE)
2. [SSE](#http-with-sse) (HTTP with Server-Sent Events)
3. [HTTP](#http-stateless) (HTTP using POST requests)

Transports **stdio** and **SSE** are _statefull_ transports, while **HTTP** is _stateless_.
pcingola marked this conversation as resolved.
Show resolved Hide resolved
Servers **MUST** support one or more of **stdio**, **SSE**, or **HTTP** transports.
Clients **SHOULD** support stdio whenever possible.

It is also possible for clients and servers to implement
Expand Down Expand Up @@ -46,7 +49,7 @@ sequenceDiagram
deactivate Server Process
```

## HTTP with SSE
## SSE

In the **SSE** transport, the server operates as an independent process that can handle
multiple client connections.
Expand Down Expand Up @@ -78,6 +81,30 @@ sequenceDiagram
Client->>Server: Close SSE connection
```

## HTTP

The **HTTP** transport is _stateless_.

If the server supports **HTTP** _stateless_ transport, the server **MUST** provide
one regular HTTP POST endpoint for clients to send messages to the server.

In the **HTTP** transport, the server operates as an independent process that
can handle multiple client connections. The server **MAY** answer to each request
independently. The server **MAY NOT** have memory of any client capabilites, client
supported versions, or previous client interations.

Server requests and server notifications **MAY NOT** be implemented in **HTTP** _stateless_ transport.
pcingola marked this conversation as resolved.
Show resolved Hide resolved

```mermaid
sequenceDiagram
participant Client
participant Server

loop Message Exchange
Client->>Server: HTTP POST messages
end
```

## Custom Transports

Clients and servers **MAY** implement additional custom transport mechanisms to suit
Expand Down
10 changes: 6 additions & 4 deletions docs/specification/2024-11-05/server/resources.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ The capability supports two optional features:
resources changes.

Both `subscribe` and `listChanged` are optional&mdash;servers can support neither,
either, or both:
either, or both (_stateless_ servers **SHALL NOT** implement either of them):

```json
{
Expand Down Expand Up @@ -209,8 +209,8 @@ capability **SHOULD** send a notification:

### Subscriptions

The protocol supports optional subscriptions to resource changes. Clients can subscribe
to specific resources and receive notifications when they change:
When _statfull_ transports are used, the protocol supports optional subscriptions to resource
pcingola marked this conversation as resolved.
Show resolved Hide resolved
changes. Clients can subscribe to specific resources and receive notifications when they change:

**Subscribe Request:**

Expand Down Expand Up @@ -269,7 +269,7 @@ sequenceDiagram
A resource definition includes:

- `uri`: Unique identifier for the resource
- `name`: Human-readable name
- `name`: Optional human-readable name
- `description`: Optional description
- `mimeType`: Optional MIME type

Expand All @@ -282,6 +282,7 @@ Resources can contain either text or binary data:
```json
{
"uri": "file:///example.txt",
"name": "An example text file",
"mimeType": "text/plain",
"text": "Resource content"
}
Expand All @@ -292,6 +293,7 @@ Resources can contain either text or binary data:
```json
{
"uri": "file:///example.png",
"name": "An example image",
"mimeType": "image/png",
"blob": "base64-encoded-data"
}
Expand Down