Skip to content
Merged
Show file tree
Hide file tree
Changes from all 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
3 changes: 2 additions & 1 deletion docs/docs.json
Original file line number Diff line number Diff line change
Expand Up @@ -420,7 +420,8 @@
"seps/2133-extensions",
"seps/2148-contributor-ladder",
"seps/2149-working-group-charter-template",
"seps/2243-http-standardization"
"seps/2243-http-standardization",
"seps/2567-sessionless-mcp"
]
},
{
Expand Down
293 changes: 293 additions & 0 deletions docs/seps/2567-sessionless-mcp.mdx

Large diffs are not rendered by default.

3 changes: 2 additions & 1 deletion docs/seps/index.mdx

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

18 changes: 9 additions & 9 deletions docs/specification/draft/architecture/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,8 @@ title: Architecture
The Model Context Protocol (MCP) follows a client-host-server architecture where each
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.
isolating concerns. Built on JSON-RPC, MCP provides a protocol focused on context
exchange and sampling coordination between clients and servers.

## Core Components

Expand Down Expand Up @@ -60,7 +60,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 connection per server
- Handles protocol negotiation and capability exchange
- Routes protocol messages bidirectionally
- Manages subscriptions and notifications
Expand Down Expand Up @@ -115,12 +115,12 @@ implementation:

The Model Context Protocol uses a capability-based negotiation system where clients and
servers explicitly declare their supported features during initialization. Capabilities
determine which protocol features and primitives are available during a session.
determine which protocol features and primitives are available during a connection.

- Servers declare capabilities like resource subscriptions, tool support, and prompt
templates
- Clients declare capabilities like sampling support and notification handling
- Both parties must respect declared capabilities throughout the session
- Both parties must respect declared capabilities throughout the connection
- Additional capabilities can be negotiated through extensions to the protocol

```mermaid
Expand All @@ -130,10 +130,10 @@ sequenceDiagram
participant Server

Host->>+Client: Initialize client
Client->>+Server: Initialize session with capabilities
Client->>+Server: Initialize with capabilities
Server-->>Client: Respond with supported capabilities

Note over Host,Server: Active Session with Negotiated Features
Note over Host,Server: Active Connection with Negotiated Features

loop Client Requests
Host->>Client: User- or model-initiated action
Expand All @@ -155,11 +155,11 @@ sequenceDiagram
end

Host->>Client: Terminate
Client->>-Server: End session
Client->>-Server: End connection
deactivate Server
```

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

- Implemented [server features](/specification/draft/server) must be advertised in the
Expand Down
3 changes: 1 addition & 2 deletions docs/specification/draft/basic/authorization.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -539,8 +539,7 @@ Specifically:
Authorization: Bearer <access-token>
```

Note that authorization **MUST** be included in every HTTP request from client to server,
even if they are part of the same logical session.
Note that authorization **MUST** be included in every HTTP request from client to server.

2. Access tokens **MUST NOT** be included in the URI query string

Expand Down
7 changes: 3 additions & 4 deletions docs/specification/draft/basic/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,7 @@ title: Overview
The Model Context Protocol consists of several key components that work together:

- **Base Protocol**: Core JSON-RPC message types
- **Lifecycle Management**: Connection initialization, capability negotiation, and
session control
- **Lifecycle Management**: Connection initialization and capability negotiation
- **Authorization**: Authentication and authorization framework for HTTP-based transports
- **Server Features**: Resources, prompts, and tools exposed by servers
- **Client Features**: Sampling and root directory lists provided by clients
Expand Down Expand Up @@ -45,8 +44,8 @@ these types of messages:

- Requests **MUST** include a string or integer ID.
- Unlike base JSON-RPC, the ID **MUST NOT** be `null`.
- The request ID **MUST NOT** have been previously used by the requestor within the same
session.
- The request ID **MUST NOT** match the ID of any other request the sender has issued and
not yet received a response for.

### Responses

Expand Down
2 changes: 1 addition & 1 deletion docs/specification/draft/basic/lifecycle.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -189,7 +189,7 @@ For details, see [the Protocol Version Header section in Transports](/specificat
#### Capability Negotiation

Client and server capabilities establish which optional protocol features will be
available during the session.
available during the connection.

Key capabilities include:

Expand Down
52 changes: 6 additions & 46 deletions docs/specification/draft/basic/transports.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -121,8 +121,6 @@ MCP endpoint.
- The server **MAY** send JSON-RPC _requests_ and _notifications_ before sending the
JSON-RPC _response_. These messages **MUST** relate to the originating client
_request_.
- The server **MAY** terminate the SSE stream if the [session](#session-management)
expires.
- After the JSON-RPC _response_ has been sent, the server **SHOULD** terminate the
SSE stream.
- Disconnection **MAY** occur at any time (e.g., due to network conditions).
Expand Down Expand Up @@ -174,9 +172,7 @@ lost:

1. Servers **MAY** attach an `id` field to their SSE events, as described in the
[SSE standard](https://html.spec.whatwg.org/multipage/server-sent-events.html#event-stream-interpretation).
- If present, the ID **MUST** be globally unique across all streams within that
[session](#session-management)—or all streams with that specific client, if session
management is not in use.
- If present, the ID **MUST** be globally unique across all streams.
- Event IDs **SHOULD** encode sufficient information to identify the originating
stream, enabling the server to correlate a `Last-Event-ID` to the correct stream.
2. If the client wishes to resume after a disconnection (whether due to network failure
Expand All @@ -195,38 +191,6 @@ lost:
In other words, these event IDs should be assigned by servers on a _per-stream_ basis, to
act as a cursor within that particular stream.

### Session Management

An MCP "session" consists of logically related interactions between a client and a
server, beginning with the [initialization phase](/specification/draft/basic/lifecycle). To support
servers which want to establish stateful sessions:

1. A server using the Streamable HTTP transport **MAY** assign a session ID at
initialization time, by including it in an `MCP-Session-Id` header on the HTTP
response containing the `InitializeResult`.
- The session ID **SHOULD** be globally unique and cryptographically secure (e.g., a
securely generated UUID, a JWT, or a cryptographic hash).
- The session ID **MUST** only contain visible ASCII characters (ranging from 0x21 to
0x7E).
- The client **MUST** handle the session ID in a secure manner, see [Session Hijacking mitigations](/specification/draft/basic/security_best_practices#session-hijacking) for more details.
2. If an `MCP-Session-Id` is returned by the server during initialization, clients using
the Streamable HTTP transport **MUST** include it in the `MCP-Session-Id` header on
all of their subsequent HTTP requests.
- Servers that require a session ID **SHOULD** respond to requests without an
`MCP-Session-Id` header (other than initialization) with HTTP 400 Bad Request.
3. The server **MAY** terminate the session at any time, after which it **MUST** respond
to requests containing that session ID with HTTP 404 Not Found.
4. When a client receives HTTP 404 in response to a request containing an
`MCP-Session-Id`, it **MUST** start a new session by sending a new `InitializeRequest`
without a session ID attached.
5. Clients that no longer need a particular session (e.g., because the user is leaving
the client application) **SHOULD** send an HTTP DELETE to the MCP endpoint with the
`MCP-Session-Id` header, to explicitly terminate the session.
- The server **MAY** respond to this request with HTTP 405 Method Not Allowed,
indicating that the server does not allow clients to terminate sessions. If the
server returns HTTP 405, it **MUST** include an `Allow` header listing the methods
it does support.

### Sequence Diagram

```mermaid
Expand All @@ -237,13 +201,13 @@ sequenceDiagram
note over Client, Server: initialization

Client->>+Server: POST InitializeRequest
Server->>-Client: InitializeResponse<br>MCP-Session-Id: 1868a90c...
Server->>-Client: InitializeResponse

Client->>+Server: POST InitializedNotification<br>MCP-Session-Id: 1868a90c...
Client->>+Server: POST InitializedNotification
Server->>-Client: 202 Accepted

note over Client, Server: client requests
Client->>+Server: POST ... request ...<br>MCP-Session-Id: 1868a90c...
Client->>+Server: POST ... request ...

alt single HTTP response
Server->>Client: ... response ...
Expand All @@ -256,11 +220,11 @@ sequenceDiagram
deactivate Server

note over Client, Server: client notifications/responses
Client->>+Server: POST ... notification/response ...<br>MCP-Session-Id: 1868a90c...
Client->>+Server: POST ... notification/response ...
Server->>-Client: 202 Accepted

note over Client, Server: server requests
Client->>+Server: GET<br>MCP-Session-Id: 1868a90c...
Client->>+Server: GET
loop while connection remains open
Server-)Client: ... SSE messages from server ...
end
Expand Down Expand Up @@ -306,7 +270,6 @@ These headers are **REQUIRED** for compliance.
```http
POST /mcp HTTP/1.1
Content-Type: application/json
Mcp-Session-Id: 1f3a4b5c-6d7e-8f9a-0b1c-2d3e4f5a6b7c
Mcp-Method: tools/call
Mcp-Name: get_weather

Expand All @@ -328,7 +291,6 @@ Mcp-Name: get_weather
```http
POST /mcp HTTP/1.1
Content-Type: application/json
Mcp-Session-Id: 1f3a4b5c-6d7e-8f9a-0b1c-2d3e4f5a6b7c
Mcp-Method: resources/read
Mcp-Name: file:///projects/myapp/config.json

Expand Down Expand Up @@ -369,7 +331,6 @@ Mcp-Method: initialize
```http
POST /mcp HTTP/1.1
Content-Type: application/json
Mcp-Session-Id: 1f3a4b5c-6d7e-8f9a-0b1c-2d3e4f5a6b7c
Mcp-Method: notifications/initialized

{
Expand Down Expand Up @@ -486,7 +447,6 @@ including the tool name and the reason for rejection.
```http
POST /mcp HTTP/1.1
Content-Type: application/json
Mcp-Session-Id: 1f3a4b5c-6d7e-8f9a-0b1c-2d3e4f5a6b7c
Mcp-Method: tools/call
Mcp-Name: execute_sql
Mcp-Param-Region: us-west1
Expand Down
2 changes: 1 addition & 1 deletion docs/specification/draft/basic/utilities/ping.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ the client or server can initiate a ping by sending a `ping` request.
<Warning>

`ping` is an MCP-level liveness check and **MAY** be sent by either party at any
time on an established session/connection.
time on an established connection.

In Streamable HTTP, implementations **SHOULD** prefer transport-level SSE
keepalive mechanisms for idle-connection maintenance; `ping` remains available
Expand Down
2 changes: 1 addition & 1 deletion docs/specification/draft/changelog.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ the previous revision, [2025-11-25](/specification/2025-11-25).

## Major changes

N/A
1. Remove protocol-level sessions and the `Mcp-Session-Id` header from the Streamable HTTP transport. List endpoints (`tools/list`, `resources/list`, `prompts/list`) no longer vary per-connection. Servers that need cross-call state use explicit, server-minted handles passed as ordinary tool arguments ([SEP-2567](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2567)).

## Minor changes

Expand Down
1 change: 0 additions & 1 deletion docs/specification/draft/client/elicitation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -531,7 +531,6 @@ Elicitations do not require that the server maintain state about users with the

However, if state is stored, servers implementing elicitation **MUST** securely associate this state with individual users following the guidelines in the [security best practices](/docs/tutorials/security/security_best_practices) document. Specifically:

- State **MUST NOT** be associated with session IDs alone
- State storage **MUST** be protected against unauthorized access
- For remote MCP servers, user identification **MUST** be derived from credentials acquired via [MCP authorization](../basic/authorization) when possible (e.g. `sub` claim)

Expand Down
8 changes: 6 additions & 2 deletions docs/specification/draft/server/prompts.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -47,8 +47,12 @@ available prompts changes.

Servers that declare the `prompts` capability **MUST** respond to `prompts/list` requests
with the set of prompts currently available to the requesting client. This set **MAY** be
empty and **MAY** change over the lifetime of the connection (see
[List Changed Notification](#list-changed-notification)).
empty and **MAY** change over time (see
[List Changed Notification](#list-changed-notification)), but **MUST NOT** vary
per-connection or as a side effect of other requests on the connection. The set
**MAY** vary by the authorization presented on the request — for example, returning
only the prompts the caller's granted scopes permit — since credentials are
per-request input, not connection state.

## Protocol Messages

Expand Down
8 changes: 6 additions & 2 deletions docs/specification/draft/server/resources.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -82,8 +82,12 @@ either, or both:

Servers that declare the `resources` capability **MUST** respond to `resources/list`
requests with the set of resources currently available to the requesting client. This set
**MAY** be empty and **MAY** change over the lifetime of the connection (see
[List Changed Notification](#list-changed-notification)).
**MAY** be empty and **MAY** change over time (see
[List Changed Notification](#list-changed-notification)), but **MUST NOT** vary
per-connection or as a side effect of other requests on the connection. The set
**MAY** vary by the authorization presented on the request — for example, returning
only the resources the caller's granted scopes permit — since credentials are
per-request input, not connection state.

## Protocol Messages

Expand Down
63 changes: 61 additions & 2 deletions docs/specification/draft/server/tools.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -52,8 +52,12 @@ available tools changes.

Servers that declare the `tools` capability **MUST** respond to `tools/list` requests
with the set of tools currently available to the requesting client. This set **MAY** be
empty and **MAY** change over the lifetime of the connection (see
[List Changed Notification](#list-changed-notification)).
empty and **MAY** change over time (see
[List Changed Notification](#list-changed-notification)), but **MUST NOT** vary
per-connection or as a side effect of other requests on the connection. The set
**MAY** vary by the authorization presented on the request — for example, returning
only the tools the caller's granted scopes permit — since credentials are
per-request input, not connection state.

Servers **SHOULD** return tools in a deterministic order (i.e., the same ordering across
requests when the underlying set of tools has not changed). Deterministic ordering enables
Expand Down Expand Up @@ -599,6 +603,61 @@ Providing an output schema helps clients and LLMs understand and properly handle
}
```

## Stateful Tools

<Note>

This section is non-normative guidance for tool design. The protocol has no
concept of a state handle; from the wire's perspective a handle is an ordinary
string in a tool result and an ordinary argument to subsequent tool calls.

</Note>

MCP has no protocol-level session, so a server cannot rely on implicit
per-connection state to relate one tool call to the next. Servers that need to
maintain state across calls — a shopping cart, an open browser context, a
database transaction — should do so by returning an explicit handle from a
creation tool and accepting that handle as an argument on subsequent calls.

For example, a server that manages a shopping cart might expose:

```jsonc
// → tools/call
{ "name": "create_basket", "arguments": {} }

// ← result
{
"content": [{ "type": "text", "text": "Created basket bsk_a1b2c3" }],
"structuredContent": { "basket_id": "bsk_a1b2c3" }
}

// → tools/call
{
"name": "add_item",
"arguments": { "basket_id": "bsk_a1b2c3", "sku": "..." }
}
```

The model is responsible for carrying `basket_id` forward; the server stores
the cart contents under that key and looks them up on each call.

When designing handles, servers should consider:

- **Authorization.** For authenticated servers, a handle is a name, not a
capability. The server should validate the caller's authorization against the
handle on every call. For unauthenticated servers, where the handle is
necessarily a bearer token, it should be generated with sufficient entropy
(e.g., a UUIDv4) and given a bounded lifetime.
- **Opacity.** Handles that encode internal structure invite parsing or
guessing; opaque identifiers do not.
- **Lifetime.** Because handles outlive any single connection, the server's
retention policy should be stated in the creation tool's description (e.g.,
"baskets expire after 24 hours of inactivity") so the model can see it when
deciding to create state.
- **Expiry errors.** A call against an expired or unknown handle should return
a tool execution error that says so, so the model can recover by creating a
new one.

## Error Handling

Tools use two error reporting mechanisms:
Expand Down
1 change: 0 additions & 1 deletion docs/specification/draft/server/utilities/pagination.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,6 @@ The following MCP operations support pagination:
- Don't make any determination based on cursor value other than whether a
non-null value was provided (e.g. an empty string is a valid cursor and
thus **MUST NOT** be treated as the end of results)
- Don't persist cursors across sessions

## Error Handling

Expand Down
Loading
Loading