Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
69 commits
Select commit Hold shift + click to select a range
ca30fd7
chore: migrate SEP-1442 into PR-based SEP format
kurtisvg Apr 14, 2026
8266c2a
chore: assign PR number 2575 to SEP
kurtisvg Apr 14, 2026
ef60c11
chore: set sponsor
kurtisvg Apr 14, 2026
d02d153
feat: remove session content and clean up SEP
kurtisvg Apr 14, 2026
74f0418
chore: generate SEP docs
kurtisvg Apr 14, 2026
59e31eb
feat: address review feedback on SEP-2575
kurtisvg Apr 14, 2026
9535230
chore: regenerate and format SEP docs
kurtisvg Apr 14, 2026
bf5ed88
fix: use io.modelcontextprotocol/ prefix for _meta keys
kurtisvg Apr 15, 2026
9692bc0
fix: simplify security implications section
kurtisvg Apr 15, 2026
a17e8c1
feat: rename to notifications/listen, remove GET endpoint, deprecate …
kurtisvg Apr 15, 2026
16c83ea
fix: rename mcpProtocolVersion to protocolVersion
kurtisvg Apr 16, 2026
a002745
feat: move notification subscriptions into notifications/listen params
kurtisvg Apr 16, 2026
38a8ba5
feat: add MissingRequiredClientCapability error, use TS interfaces fo…
kurtisvg Apr 16, 2026
dc78242
feat: use RequestMetaObject instead of Request for schema diffs
kurtisvg Apr 16, 2026
e835622
fix: clarify first SSE event wording
kurtisvg Apr 16, 2026
f0d64cc
chore: regenerate docs after rebase
kurtisvg Apr 16, 2026
0a79f5e
fix: clarify HTTP header and payload must match
kurtisvg Apr 20, 2026
1ffcaf7
fix: include roots, logLevel, clientInfo in RequestMetaObject diff
kurtisvg Apr 20, 2026
4efd9db
chore: add open question on _meta vs top-level fields
kurtisvg Apr 20, 2026
3a24abc
fix: clarify unsupported protocol version covers known and unknown ve…
kurtisvg Apr 20, 2026
2f8e87d
fix: align UnsupportedProtocolVersionError with current spec
kurtisvg Apr 20, 2026
f760e1f
docs: add FAQ on server/discover vs Server Card
kurtisvg Apr 20, 2026
f39f22a
fix: rename DiscoveryRequest/Result to DiscoverRequest/Result
kurtisvg Apr 20, 2026
c212b42
fix: clarify server/discover is required for servers, optional for cl…
kurtisvg Apr 20, 2026
30c3c2d
fix: require clientCapabilities on every request
kurtisvg Apr 20, 2026
496a9c5
fix: explain how SEP-2260 and SEP-2322 eliminate server-to-client req…
kurtisvg Apr 20, 2026
1529765
fix: tighten missing capability error wording
kurtisvg Apr 20, 2026
faf8e67
fix: define absence semantics for _meta fields and defer roots to MRTR
kurtisvg Apr 20, 2026
c4a0c19
fix: restructure Per-Request Client Capabilities section
kurtisvg Apr 20, 2026
09cbb49
fix: remove ping RPC
kurtisvg Apr 20, 2026
b9f1753
fix: add logLevel to notifications/listen subscription filter
kurtisvg Apr 20, 2026
7a541b8
fix: rename notifications/listen to subscriptions/listen
kurtisvg Apr 20, 2026
dc4c2aa
fix: have ack notification confirm subscriptions server agreed to
kurtisvg Apr 20, 2026
b6c82ec
fix: specify request cancellation behavior for HTTP and STDIO
kurtisvg Apr 24, 2026
a84dbfa
fix: make _meta required in SubscriptionsListenRequest
kurtisvg Apr 24, 2026
6c420f4
feat: support multiple subscriptions with request ID correlation
kurtisvg Apr 24, 2026
a1968d5
fix: clarify STDIO backward-compat probe applies to dual-version clie…
kurtisvg Apr 24, 2026
da316b0
fix: clarify missing capability check is for individual capabilities
kurtisvg Apr 24, 2026
87b48c6
fix: clarify subscription lifecycle and remove stale result wording
kurtisvg Apr 24, 2026
369e7b0
feat: remove resumable streams in favor of tasks primitive
kurtisvg Apr 24, 2026
f7d68ef
fix: clarify ping is removed in both directions
kurtisvg Apr 24, 2026
4a0661f
docs: rewrite lifecycle.mdx (SEP-2575)
kurtisvg May 7, 2026
2a538c6
docs: rewrite transports.mdx (SEP-2575)
kurtisvg May 8, 2026
6692e2b
docs: update index.mdx for stateless model (SEP-2575)
kurtisvg May 8, 2026
cee8188
docs: update cancellation.mdx for stateless model (SEP-2575)
kurtisvg May 8, 2026
1b04197
docs: remove ping from draft spec (SEP-2575)
kurtisvg May 8, 2026
066fb1d
docs: replace resource subscribe with subscriptions/listen (SEP-2575)
kurtisvg May 8, 2026
a500505
docs: add subscriptions/listen page and update resources/logging (SEP…
kurtisvg May 8, 2026
d962745
docs: update architecture.mdx for stateless model (SEP-2575)
kurtisvg May 8, 2026
db11120
docs: sweep guides for stateless model (SEP-2575)
kurtisvg May 8, 2026
dcb5267
docs: fix stale initialization references in draft spec (SEP-2575)
kurtisvg May 8, 2026
b460206
chore: mark SEP-2575 as Accepted
kurtisvg May 8, 2026
dd1cdcf
revert: restore guide files to pre-SEP-2575 state
kurtisvg May 8, 2026
4f0f786
fix: remove logLevel from subscriptions/listen filter
kurtisvg May 8, 2026
3c66ee3
feat: update schema for stateless MCP (SEP-2575)
kurtisvg May 8, 2026
195a56d
docs: add server/discover page and note servers MUST implement it (SE…
kurtisvg May 8, 2026
2d7af98
docs: document MissingRequiredClientCapabilityError in per-request _m…
kurtisvg May 8, 2026
ad108c5
docs: remove stale roots listChanged references
kurtisvg May 8, 2026
81e14b5
docs: document HTTP 404 / -32601 response for unsupported RPC methods
kurtisvg May 9, 2026
4e07d4d
docs: add SEP-2575 changelog entries
kurtisvg May 9, 2026
3d5cf57
docs: replace 'Stateful connections' with stateless model in draft index
kurtisvg May 9, 2026
ce64031
docs: update architecture page
kurtisvg May 9, 2026
0d3a2fe
docs: remove stale HTTP GET stream reference from tasks
kurtisvg May 9, 2026
043f878
docs: update prompts list changed notification to use subscriptions/l…
kurtisvg May 9, 2026
64988f9
docs: update tools list changed notification to use subscriptions/listen
kurtisvg May 9, 2026
0f99067
docs: document concurrent subscriptions, teardown, reconnection, and …
kurtisvg May 9, 2026
91e1108
docs: add cross-reference to HTTP 404 rule in server/discover
kurtisvg May 9, 2026
9672899
docs: clarify UnsupportedProtocolVersionError does not trigger initia…
kurtisvg May 9, 2026
d6b2764
feat: make _meta required in RequestParams and update examples
kurtisvg May 9, 2026
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
6 changes: 4 additions & 2 deletions docs/docs.json
Original file line number Diff line number Diff line change
Expand Up @@ -322,8 +322,8 @@
"group": "Utilities",
"pages": [
"specification/draft/basic/utilities/cancellation",
"specification/draft/basic/utilities/ping",
"specification/draft/basic/utilities/progress",
"specification/draft/basic/utilities/subscriptions",
"specification/draft/basic/utilities/tasks",
"specification/draft/basic/utilities/mrtr"
]
Expand All @@ -342,6 +342,7 @@
"group": "Server Features",
"pages": [
"specification/draft/server/index",
"specification/draft/server/discover",
"specification/draft/server/prompts",
"specification/draft/server/resources",
"specification/draft/server/tools",
Expand Down Expand Up @@ -428,7 +429,8 @@
"group": "Accepted",
"pages": [
"seps/2207-oidc-refresh-token-guidance",
"seps/2260-Require-Server-requests-to-be-associated-with-Client-requests"
"seps/2260-Require-Server-requests-to-be-associated-with-Client-requests",
"seps/2575-stateless-mcp"
]
},
{
Expand Down
802 changes: 802 additions & 0 deletions docs/seps/2575-stateless-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.

78 changes: 40 additions & 38 deletions docs/specification/draft/architecture/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,12 @@ title: Architecture
<div id="enable-section-numbers" />

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 protocol focused on context
exchange and sampling coordination between clients and servers.
host can run multiple client instances. MCP is a stateless protocol: every request is
self-contained and carries its own protocol version, client identity, and capabilities.
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 protocol focused on context exchange and sampling coordination between
clients and servers.

## Core Components

Expand Down Expand Up @@ -58,10 +60,10 @@ The host process acts as the container and coordinator:

### Clients

Each client is created by the host and maintains an isolated server connection:
Each client is created by the host and communicates with exactly one server:

- Establishes one connection per server
- Handles protocol negotiation and capability exchange
- Communicates with exactly one server
- Attaches protocol version and capabilities to every request
- Routes protocol messages bidirectionally
- Manages subscriptions and notifications
- Maintains security boundaries between servers
Expand All @@ -75,7 +77,7 @@ Servers provide specialized context and capabilities:

- Expose resources, tools and prompts via MCP primitives
- Operate independently with focused responsibilities
- Request sampling through client interfaces
- Request client input (sampling, elicitation, roots) via `IncompleteResponse` within a reply
- Must respect security constraints
- Can be local processes or remote services

Expand All @@ -100,7 +102,7 @@ implementation:
servers**
- Servers receive only necessary contextual information
- Full conversation history stays with the host
- Each server connection maintains isolation
- Each server maintains isolation
- Cross-server interactions are controlled by the host
- Host process enforces security boundaries

Expand All @@ -114,13 +116,16 @@ implementation:
## Capability Negotiation

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 connection.
servers declare their supported features on each request. Clients include their
capabilities in `_meta.io.modelcontextprotocol/clientCapabilities` on every request.
Servers advertise their capabilities in response to
[`server/discover`](/specification/draft/server/discover), which clients may call before
any other request for up-front capability discovery.

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

```mermaid
Expand All @@ -129,43 +134,40 @@ sequenceDiagram
participant Client
participant Server

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

Note over Host,Server: Active Connection with Negotiated Features
opt Discovery
Client->>Server: server/discover
Server-->>Client: supported versions + capabilities
end

loop Client Requests
Host->>Client: User- or model-initiated action
Client->>Server: Request (tools/resources)
Client->>Server: Request (with _meta: version, clientInfo, clientCapabilities)
alt Server requires client input
Server-->>Client: IncompleteResponse (e.g. sampling/createMessage)
Client->>Host: Forward to AI
Host-->>Client: AI response
Client->>Server: Original request (with input)
end
Server-->>Client: Response
Client-->>Host: Update UI or respond to model
end

loop Server Requests
Server->>Client: Request (sampling)
Client->>Host: Forward to AI
Host-->>Client: AI response
Client-->>Server: Response
opt Subscriptions
Client->>Server: subscriptions/listen (toolsListChanged, resourceSubscriptions, …)
Server--)Client: notifications/subscriptions/acknowledged
loop Stream
Server--)Client: notifications/* (tagged with subscriptionId)
end
end

loop Notifications
Server--)Client: Resource updates
Client--)Server: Status changes
end

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

Each capability unlocks specific protocol features for use during the connection. For
example:
Each capability unlocks specific protocol features on a per-request basis. For example:

- Implemented [server features](/specification/draft/server) must be advertised in the
server's capabilities
- Emitting resource subscription notifications requires the server to declare
subscription support
- Receiving resource update notifications requires opening a
[`subscriptions/listen`](/specification/draft/basic/utilities/subscriptions) stream
with the desired resource URIs
- Tool invocation requires the server to declare tool capabilities
- [Sampling](/specification/draft/client) requires the client to declare support in its
capabilities
Expand Down
30 changes: 29 additions & 1 deletion docs/specification/draft/basic/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +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 and capability negotiation
- **Lifecycle Management**: Protocol version negotiation and per-request capability declaration
- **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 @@ -225,6 +225,34 @@ may reserve particular names for purpose-specific metadata, as declared in those
- Unless empty, MUST begin and end with an alphanumeric character (`[a-z0-9A-Z]`).
- MAY contain hyphens (`-`), underscores (`_`), dots (`.`), and alphanumerics in between.

**Per-request protocol fields:**

Every client request **MUST** include the following `io.modelcontextprotocol/*` fields
in `_meta`. Servers use these to identify the client and the protocol version in use
without relying on any prior connection state. See
[Lifecycle][lifecycle] for version negotiation rules.

| Key | Type | Required | Description |
| -------------------------------------------- | -------------------- | -------- | ----------------------------------------------------------- |
| `io.modelcontextprotocol/protocolVersion` | `string` | Yes | Protocol version for this request (e.g., `"DRAFT-2026-v1"`) |
| `io.modelcontextprotocol/clientInfo` | `Implementation` | Yes | Client name and version |
| `io.modelcontextprotocol/clientCapabilities` | `ClientCapabilities` | Yes | Client capabilities relevant to this request |
Comment thread
kurtisvg marked this conversation as resolved.
| `io.modelcontextprotocol/logLevel` | `LoggingLevel` | No | Minimum log level the server should emit for this request |

A server **MUST NOT** rely on capabilities the client has not declared. If
processing a request requires a capability the client did not include in
`io.modelcontextprotocol/clientCapabilities`, the server **MUST** return a
[`MissingRequiredClientCapabilityError`](/specification/draft/schema#missingrequiredclientcapabilityerror)
(`-32003`) whose `data.requiredCapabilities` lists the missing capabilities. On
HTTP, the response status **MUST** be `400 Bad Request`.

On notifications delivered via a [`subscriptions/listen`][subscriptions-listen] stream,
the server **MUST** include `io.modelcontextprotocol/subscriptionId` in `_meta` so the
client can correlate the notification with the originating subscription request.

[lifecycle]: /specification/draft/basic/lifecycle
[subscriptions-listen]: /specification/draft/basic/utilities/subscriptions

**OpenTelemetry trace context:**

As an exception to the prefix requirement above, the keys `traceparent`, `tracestate`, and
Expand Down
Loading
Loading