Skip to content

Commit 8fa44eb

Browse files
committed
docs(spec): consolidate back-compat rule and broaden stdio fallback
Move the per-transport rule for "modern vs legacy server" detection into the Lifecycle: Backward Compatibility section as the single source of truth, and replace the duplicated paragraphs in Transports (stdio + HTTP) and Discover with brief cross-links. For the stdio probe, broaden the fallback condition: legacy servers are not required to answer an unknown pre-initialize method with -32601 (or to respond at all), so the client falls back to initialize on any error other than UnsupportedProtocolVersionError, or on no response within a reasonable timeout. The client also restarts the server process before sending initialize, since the legacy server may be in an undefined state after the unrecognized probe.
1 parent 33c3724 commit 8fa44eb

3 files changed

Lines changed: 26 additions & 35 deletions

File tree

docs/specification/draft/basic/lifecycle.mdx

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -112,12 +112,18 @@ both kinds of servers can detect which is present:
112112
- **STDIO.** Because there is no per-request status code to drive fallback,
113113
a client that supports both eras **SHOULD** probe with
114114
[`server/discover`](/specification/draft/server/discover) first,
115-
setting its preferred modern version in `_meta`. If the server returns
116-
`Method not found` (`-32601`), fall back to the legacy `initialize`
117-
handshake. If the server returns `UnsupportedProtocolVersionError`, the
118-
server speaks a version of MCP without `initialize` — use one of the
119-
versions in its advertised `supported` list instead of falling back to
120-
`initialize`.
115+
setting its preferred modern version in `_meta`. The client interprets the
116+
response as follows:
117+
- **`UnsupportedProtocolVersionError`**: the server speaks modern MCP
118+
without the requested version. Retry using one of the versions in its
119+
advertised `supported` list rather than falling back to `initialize`.
120+
- **Any other error response, or no response within a reasonable timeout**:
121+
restart the server process and perform the legacy `initialize` handshake
122+
on the fresh process. Legacy servers are not required to use any
123+
particular error code (or to respond at all) for an unknown method
124+
received before `initialize`, so the fallback cannot rely on a single
125+
code such as `-32601`, and the server may be left in an undefined state
126+
after the unrecognized probe.
121127

122128
A client that only supports modern (per-request-metadata) versions does not
123129
need to probe — it simply sends its preferred version and handles

docs/specification/draft/basic/transports.mdx

Lines changed: 10 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -115,16 +115,11 @@ re-established after restart.
115115

116116
### Backward Compatibility
117117

118-
A client that supports both modern (per-request-metadata) MCP versions and a
119-
legacy version that requires an `initialize` handshake **SHOULD** probe with
120-
[`server/discover`][server-discover] before sending
121-
any other request. If the server returns `Method not found` (`-32601`), the
122-
client falls back to the legacy `initialize` handshake. If the server returns
123-
`UnsupportedProtocolVersionError`, it speaks a version of MCP without
124-
`initialize` — the client **SHOULD** retry using one of the versions in the
125-
advertised `supported` list rather than falling back to `initialize`. See
126-
[Lifecycle: Backward Compatibility][lifecycle-compat]
127-
for details.
118+
A client that interoperates with both modern (per-request-metadata) MCP
119+
versions and a legacy version requiring an `initialize` handshake **SHOULD**
120+
probe with [`server/discover`][server-discover] before sending any other
121+
request. See [Lifecycle: Backward Compatibility][lifecycle-compat] for the
122+
rule that determines when to fall back to `initialize`.
128123

129124
A client that only supports modern versions does not need to probe.
130125

@@ -585,22 +580,11 @@ a JSON-RPC error response.
585580

586581
### Backward Compatibility
587582

588-
A client that supports both modern (per-request-metadata) MCP versions and a
589-
legacy version that requires an `initialize` handshake **MAY** detect which
590-
era the server implements by attempting a modern request first. On
591-
`400 Bad Request`, the client **SHOULD** inspect the response body before
592-
falling back: modern servers also use `400` for
593-
[`UnsupportedProtocolVersionError`][unsupported-version],
594-
`MissingRequiredClientCapabilityError`, and header-validation failures.
595-
596-
- If the body contains a recognized modern JSON-RPC error, the server speaks
597-
a modern version of MCP — retry using the advertised `supported` versions
598-
or correct the request, rather than falling back.
599-
- If the body is empty or is not a recognized modern JSON-RPC error, fall
600-
back to `initialize` and continue with the legacy version for subsequent
601-
requests.
602-
603-
See [Lifecycle: Backward Compatibility][lifecycle-compat] for details.
583+
A client that interoperates with both modern (per-request-metadata) MCP
584+
versions and a legacy version requiring an `initialize` handshake **MAY**
585+
detect which era the server implements by attempting a modern request first.
586+
See [Lifecycle: Backward Compatibility][lifecycle-compat] for the rule that
587+
determines when to fall back to `initialize`.
604588

605589
Separately, clients and servers can maintain backward compatibility with the
606590
deprecated [HTTP+SSE transport][http-sse] (from

docs/specification/draft/server/discover.mdx

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -75,10 +75,11 @@ is useful in two scenarios:
7575
- **Up-front version selection.** The client learns the server's supported
7676
versions before sending any other request, avoiding a round-trip error.
7777
- **STDIO backward-compatibility probe.** On stdio, there is no per-request
78-
HTTP status code to drive fallback. A client that supports both modern
78+
HTTP status code to drive fallback, so a client that supports both modern
7979
(per-request `_meta`) and legacy (`initialize` handshake) servers **SHOULD**
80-
send `server/discover` first. If the server returns `Method not found`
81-
(`-32601`), the client falls back to the `initialize` handshake.
80+
send `server/discover` first to detect which era the server speaks. See
81+
[Lifecycle: Backward Compatibility](/specification/draft/basic/lifecycle#backward-compatibility-with-initialization-based-versions)
82+
for the rule that determines when to fall back.
8283

8384
See [Protocol Version Negotiation](/specification/draft/basic/lifecycle#protocol-version-negotiation)
8485
for the full version-selection flow. For HTTP-specific status codes returned for

0 commit comments

Comments
 (0)