Broaden legacy fallback for MCP discovery over HTTP (#62893)

## Why

Legacy MCP servers can reject `server/discover` before JSON-RPC dispatch
because they require a session ID or reject the requested protocol version.
Their HTTP 400 response can be empty or lack a matching JSON-RPC request ID,
leaving Codex unable to start the legacy handshake.

## What changed

Retry with a sessionless `initialize` when the initial sessionless
`server/discover` receives HTTP 400 without an authentication challenge or
a JSON-RPC error code that requires validation. Preserve fallback for
recognized legacy rejections and give structured protocol version offers
precedence over error text. Once a server offers a modern version, surface
a rejected follow-up probe as a discovery failure.

## Testing

Extend mock-server coverage to verify that legacy fallback establishes a
fresh session and uses it for `tools/list`. Cover authentication challenges,
malformed and uncorrelated JSON-RPC errors, and failures after a modern
version offer.

GitOrigin-RevId: edc573e38c63b837462f1b8d84e2d8abdf62cb3e
This commit is contained in:
thomas
2026-11-21 03:51:15 +00:00
committed by copyberry
parent 63a15005de
commit bfe3c82570
2 changed files with 268 additions and 146 deletions
+125 -52
View File
@@ -12,6 +12,8 @@ use std::io;
use std::sync::Arc;
use std::sync::Mutex;
use std::sync::PoisonError;
use std::sync::atomic::AtomicBool;
use std::sync::atomic::Ordering;
use std::time::Duration;
use std::time::Instant;
@@ -82,6 +84,7 @@ pub(crate) struct StreamableHttpClientAdapter {
default_headers: HeaderMap,
auth_provider: Option<Arc<dyn AuthProviderResolver>>,
event_stream_cancellations: Arc<Mutex<HashMap<RequestId, oneshot::Sender<()>>>>,
modern_version_offered: Arc<AtomicBool>,
has_configured_headers: bool,
redirect_mode: StreamableHttpRedirectMode,
initialize_deadline: Arc<Mutex<Option<Instant>>>,
@@ -131,6 +134,7 @@ impl StreamableHttpClientAdapter {
default_headers,
auth_provider,
event_stream_cancellations: Arc::default(),
modern_version_offered: Arc::default(),
has_configured_headers,
redirect_mode,
initialize_deadline,
@@ -331,50 +335,96 @@ impl StreamableHttpClient for StreamableHttpClientAdapter {
let content_type = response_header(&response.headers, CONTENT_TYPE);
let session_id = response_header(&response.headers, HEADER_SESSION_ID);
// rmcp can send a second sessionless probe after a correlated -32022.
// Keep negotiation on the modern path for the lifetime of this transport.
let is_reoffer =
is_discovery_request && self.modern_version_offered.load(Ordering::Relaxed);
let classify = |reply, allow_uncorrelated_http_rejection| {
let reply = legacy_discovery_fallback_response(
&message,
reply,
allow_uncorrelated_http_rejection,
);
if is_discovery_request
&& let JsonRpcMessage::Request(request) = &message
&& let JsonRpcMessage::Error(error) = &reply
&& error.id.as_ref() == Some(&request.id)
{
if error.error.code == ErrorCode::UNSUPPORTED_PROTOCOL_VERSION {
self.modern_version_offered.store(true, Ordering::Relaxed);
}
if is_reoffer && error.error.code == ErrorCode::METHOD_NOT_FOUND {
return Err(StreamableHttpError::UnexpectedServerResponse(
format!(
"server rejected discovery after offering a modern protocol: {}",
error.error
)
.into(),
));
}
}
Ok(reply)
};
if !status_is_success(response.status) {
let body = collect_body(&mut body_stream, maximum_response_bytes).await?;
if !retryable_post_response_status(mcp_method.as_deref(), response.status)
&& (content_type
.as_deref()
.is_some_and(|content_type| content_type.starts_with(JSON_MIME_TYPE))
|| (mcp_method.as_deref() == Some(DiscoverRequestMethod::VALUE)
&& response.status == StatusCode::BAD_REQUEST.as_u16()
&& !has_session_id))
&& let Some(response_message) = parse_json_rpc_error(&body)
{
return Ok(StreamableHttpPostResponse::Json(
legacy_discovery_fallback_response(
&message,
response_message,
response.status == StatusCode::BAD_REQUEST.as_u16() && !has_session_id,
),
session_id,
));
}
if mcp_method.as_deref() == Some(DiscoverRequestMethod::VALUE)
&& !has_session_id
&& matches!(
StatusCode::from_u16(response.status).ok(),
Some(StatusCode::NOT_FOUND | StatusCode::METHOD_NOT_ALLOWED)
)
&& content_type
.as_deref()
.is_none_or(|content_type| !content_type.starts_with(JSON_MIME_TYPE))
&& let JsonRpcMessage::Request(request) = &message
{
let is_json = content_type
.as_deref()
.is_some_and(|value| value.starts_with(JSON_MIME_TYPE));
let sessionless_discovery =
is_discovery_request && !headers.contains_key(HEADER_SESSION_ID);
let initial_discovery = sessionless_discovery && !is_reoffer;
let discovery_bad_request =
sessionless_discovery && response.status == StatusCode::BAD_REQUEST.as_u16();
let challenge = if discovery_bad_request {
response_header(&response.headers, WWW_AUTHENTICATE.as_str())
} else {
None
};
let rpc_rejection = discovery_bad_request && requires_rpc_validation(&body);
// A legacy server may reject the version or missing session before RPC dispatch,
// so the HTTP response can lack a usable JSON-RPC envelope (or matching ID).
// https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http#backward-compatibility
let try_initialize = match StatusCode::from_u16(response.status).ok() {
Some(StatusCode::BAD_REQUEST) if initial_discovery => {
challenge.is_none() && !rpc_rejection
}
Some(StatusCode::NOT_FOUND | StatusCode::METHOD_NOT_ALLOWED) => {
initial_discovery && !is_json
}
_ => false,
};
if try_initialize && let JsonRpcMessage::Request(request) = &message {
// Signal rmcp's Auto lifecycle to start a new handshake without a session ID.
let legacy_error = ServerJsonRpcMessage::error(
ErrorData::new(
ErrorCode::METHOD_NOT_FOUND,
"legacy MCP endpoint does not support server/discover",
format!("server/discover rejected with HTTP {}", response.status),
None,
),
Some(request.id.clone()),
);
return Ok(StreamableHttpPostResponse::Json(legacy_error, session_id));
return Ok(StreamableHttpPostResponse::Json(legacy_error, None));
}
if !retryable_post_response_status(mcp_method.as_deref(), response.status)
&& (is_json || discovery_bad_request)
&& let Some(response_message) = parse_json_rpc_error(&body)
{
let reply = classify(response_message, initial_discovery && discovery_bad_request)?;
// A challenge rules out a speculative fallback, but a known legacy
// rejection still warrants initialize, which may itself return 401.
if challenge.is_none()
|| rpc_rejection
|| matches!(&reply, JsonRpcMessage::Error(error) if error.error.code == ErrorCode::METHOD_NOT_FOUND)
{
return Ok(StreamableHttpPostResponse::Json(reply, session_id));
}
}
let challenge = challenge
.map(|value| format!(" (WWW-Authenticate: {})", body_preview(value)))
.unwrap_or_default();
return Err(StreamableHttpError::UnexpectedServerResponse(
format!(
"HTTP {}: {}",
"HTTP {}: {}{challenge}",
response.status,
body_preview(String::from_utf8_lossy(&body).to_string())
)
@@ -399,9 +449,8 @@ impl StreamableHttpClient for StreamableHttpClientAdapter {
let response = serde_json::from_slice(data.as_bytes())
.map_err(StreamableHttpError::Deserialize)?;
let response = legacy_discovery_fallback_response(
&message, response, /*allow_uncorrelated_http_rejection*/ false,
);
let response =
classify(response, /*allow_uncorrelated_http_rejection*/ false)?;
if matches!(
&response,
JsonRpcMessage::Response(_) | JsonRpcMessage::Error(_)
@@ -450,11 +499,10 @@ impl StreamableHttpClient for StreamableHttpClientAdapter {
let response_message =
serde_json::from_slice(&body).map_err(StreamableHttpError::Deserialize)?;
Ok(StreamableHttpPostResponse::Json(
legacy_discovery_fallback_response(
&message,
classify(
response_message,
/*allow_uncorrelated_http_rejection*/ false,
),
)?,
session_id,
))
}
@@ -798,6 +846,28 @@ fn is_retryable_http_status(status: StatusCode) -> bool {
)
}
// Inspect the code even if the rest of the envelope is malformed. Leave version
// negotiation and method-not-found ID correlation to the existing RPC path.
fn requires_rpc_validation(body: &[u8]) -> bool {
#[derive(serde::Deserialize)]
struct Rejection {
error: Code,
}
#[derive(serde::Deserialize)]
struct Code {
code: ErrorCode,
}
serde_json::from_slice::<Rejection>(body).is_ok_and(|response| {
matches!(
response.error.code,
ErrorCode::METHOD_NOT_FOUND
| ErrorCode::HEADER_MISMATCH
| ErrorCode::MISSING_REQUIRED_CLIENT_CAPABILITY
| ErrorCode::UNSUPPORTED_PROTOCOL_VERSION
)
})
}
fn parse_json_rpc_error(body: &[u8]) -> Option<ServerJsonRpcMessage> {
match serde_json::from_slice::<ServerJsonRpcMessage>(body) {
Ok(message @ JsonRpcMessage::Error(_)) => Some(message),
@@ -864,23 +934,26 @@ pub(super) fn legacy_discovery_fallback_response(
}
_ => false,
},
JsonRpcMessage::Error(error) if error.id.as_ref() == Some(&request.id) => {
(error.error.code == ErrorCode::UNSUPPORTED_PROTOCOL_VERSION
&& error
JsonRpcMessage::Error(error)
if error.id.as_ref() == Some(&request.id)
&& error.error.code == ErrorCode::UNSUPPORTED_PROTOCOL_VERSION
&& let Some(supported) = error
.error
.data
.as_ref()
.and_then(|data| data.get("supported"))
.and_then(|supported| {
serde_json::from_value::<Vec<ProtocolVersion>>(supported.clone()).ok()
})
.is_some_and(|supported| only_known_legacy_protocol_versions(&supported)))
|| matches!(
error.error.code,
ErrorCode::UNSUPPORTED_PROTOCOL_VERSION
| ErrorCode::INVALID_REQUEST
| ErrorCode::INVALID_PARAMS
) && explicitly_rejects_modern_protocol_version(&error.error.message)
.and_then(|data| data.get("supported")) =>
{
// A structured version offer takes precedence over the human-readable message.
serde_json::from_value::<Vec<ProtocolVersion>>(supported.clone())
.is_ok_and(|versions| only_known_legacy_protocol_versions(&versions))
}
JsonRpcMessage::Error(error) if error.id.as_ref() == Some(&request.id) => {
matches!(
error.error.code,
ErrorCode::UNSUPPORTED_PROTOCOL_VERSION
| ErrorCode::INVALID_REQUEST
| ErrorCode::INVALID_PARAMS
) && explicitly_rejects_modern_protocol_version(&error.error.message)
}
JsonRpcMessage::Error(error)
if allow_uncorrelated_http_rejection
+143 -94
View File
@@ -916,11 +916,13 @@ async fn modern_legacy_fallback_preserves_authentication_required_error() -> any
let method = body["method"].as_str().expect("JSON-RPC method");
recorded.lock().expect("requests lock").push(method.into());
match method {
"server/discover" => ResponseTemplate::new(200).set_body_json(json!({
"jsonrpc": "2.0",
"id": body["id"],
"error": {"code": -32601, "message": "method not found"},
})),
"server/discover" => ResponseTemplate::new(400)
.insert_header("www-authenticate", "Bearer")
.set_body_json(json!({
"jsonrpc": "2.0",
"id": body["id"],
"error": {"code": -32601, "message": "method not found"},
})),
"initialize" => ResponseTemplate::new(401)
.insert_header("www-authenticate", "Bearer error=\"invalid_token\""),
other => panic!("unexpected authentication fallback request: {other}"),
@@ -1150,7 +1152,7 @@ async fn modern_discovery_rejects_uncorrelated_legacy_version_rejection() -> any
.respond_with(|request: &Request| {
let body: Value = request.body_json().expect("valid JSON-RPC request");
assert_eq!(body["method"], "server/discover");
ResponseTemplate::new(400).set_body_json(json!({
ResponseTemplate::new(200).set_body_json(json!({
"jsonrpc": "2.0",
"id": "unrelated-request",
"error": {
@@ -1174,14 +1176,19 @@ async fn modern_discovery_rejects_uncorrelated_legacy_version_rejection() -> any
#[tokio::test]
async fn modern_discovery_rejects_uncorrelated_method_not_found_errors() -> anyhow::Result<()> {
for response_id in [Value::Null, json!("unrelated-request")] {
for (status, response_id) in [
(200, Value::Null),
(200, json!("unrelated-request")),
(400, Value::Null),
(400, json!("unrelated-request")),
] {
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path("/mcp"))
.respond_with(move |request: &Request| {
let body: Value = request.body_json().expect("valid JSON-RPC request");
assert_eq!(body["method"], "server/discover");
ResponseTemplate::new(200).set_body_json(json!({
ResponseTemplate::new(status).set_body_json(json!({
"jsonrpc": "2.0",
"id": response_id,
"error": {"code": -32601, "message": "method not found"},
@@ -1206,63 +1213,90 @@ async fn modern_discovery_rejects_uncorrelated_method_not_found_errors() -> anyh
#[tokio::test]
async fn modern_mode_falls_back_for_legacy_http_prevalidation_errors() -> anyhow::Result<()> {
for (message, content_type) in [
(
"Bad Request: Unsupported protocol version: 2026-07-28 (supported versions: 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07)",
"application/json",
),
// tinymcp.dev omits the rejected version from its legacy error shape.
(
"Bad Request: Unsupported protocol version (supported versions: 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07)",
"application/json",
),
(
"Bad Request: Unsupported protocol version (supported versions: 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07)",
"text/plain",
),
(
"Bad Request: Unsupported protocol version (supported versions: 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07)",
"application/octet-stream",
),
(
let rejection = |id: Value, code: i64, message: &str| {
ResponseTemplate::new(400).set_body_json(json!({
"jsonrpc": "2.0", "id": id, "error": {"code": code, "message": message}
}))
};
for bad_request in [
rejection(
Value::Null,
-32000,
"Bad Request: No valid session ID provided",
"application/json",
)
.insert_header("www-authenticate", "Bearer"),
// TypeScript SDK, before a session has been established.
rejection(
Value::Null,
-32000,
"Bad Request: Mcp-Session-Id header is required",
),
rejection(Value::Null, -32000, "Bad Request: Server not initialized"),
// Python SDK 1.x, stateful and stateless HTTP respectively.
rejection(
json!("server-error"),
-32600,
"Bad Request: Missing session ID",
),
rejection(
json!("server-error"),
-32600,
"Bad Request: Unsupported protocol version: 2026-07-28. Supported versions: 2025-06-18, 2025-11-25",
),
ResponseTemplate::new(400),
ResponseTemplate::new(400).set_body_string("Bad Request"),
] {
let server = MockServer::start().await;
let observed = Arc::new(Mutex::new(Vec::<String>::new()));
let recorded = Arc::clone(&observed);
Mock::given(method("POST"))
.and(path("/mcp"))
.respond_with(move |request: &Request| {
let body: Value = request.body_json().expect("valid JSON-RPC request");
let method = body["method"].as_str().expect("JSON-RPC method");
recorded.lock().expect("requests lock").push(method.into());
match method {
"server/discover" => ResponseTemplate::new(400).set_body_raw(
serde_json::to_vec(&json!({
"jsonrpc": "2.0",
"id": null,
"error": {"code": -32000, "message": message},
}))
.expect("legacy discovery error serializes"),
content_type,
),
"initialize" => legacy_initialize_response(&body),
match body["method"].as_str().unwrap() {
"server/discover" => bad_request.clone(),
"initialize" => {
assert!(request.headers.get("mcp-session-id").is_none());
assert_eq!(body["params"]["protocolVersion"], LEGACY_VERSION);
legacy_initialize_response(&body).insert_header("mcp-session-id", "fresh")
}
"notifications/initialized" => ResponseTemplate::new(202),
other => panic!("unexpected legacy fallback method: {other}"),
"tools/list" => {
assert_eq!(request.headers["mcp-session-id"], "fresh");
ResponseTemplate::new(200).set_body_json(json!({
"jsonrpc": "2.0", "id": body["id"],
"result": {"tools": [{"name": "echo", "inputSchema": {"type": "object"}}]}
}))
}
other => panic!("unexpected method: {other}"),
}
})
.expect(3)
.expect(4)
.mount(&server)
.await;
let client = create_client(&server, McpProtocolMode::V20260728).await?;
initialize_client(&client).await?;
let tools = client.list_tools(/*params*/ None, /*timeout*/ None).await?;
assert_eq!(tools.tools[0].name, "echo");
let methods: Vec<_> = server
.received_requests()
.await
.unwrap()
.iter()
.filter(|r| r.method.as_str() == "POST")
.map(|r| {
r.body_json::<Value>().unwrap()["method"]
.as_str()
.unwrap()
.to_owned()
})
.collect();
assert_eq!(
*observed.lock().expect("requests lock"),
vec!["server/discover", "initialize", "notifications/initialized"]
methods,
[
"server/discover",
"initialize",
"notifications/initialized",
"tools/list"
]
);
client.shutdown().await;
}
@@ -1360,61 +1394,78 @@ async fn modern_mode_negotiates_a_server_selected_legacy_protocol_version() -> a
}
#[tokio::test]
async fn modern_discovery_rejects_unrecognized_or_modern_null_id_errors() -> anyhow::Result<()> {
for (status, message, content_type) in [
(400, "Bad Request: malformed request", "application/json"),
(400, "Bad Request: malformed request", "text/plain"),
async fn modern_discovery_preserves_challenges_and_malformed_modern_errors() -> anyhow::Result<()> {
for (rejection, diagnostic) in [
(
400,
"Bad Request: Unsupported protocol version: 2026-07-28 (supported versions: 2025-06-18, 2099-01-01)",
"application/json",
ResponseTemplate::new(400)
.insert_header("www-authenticate", "Bearer")
.set_body_string("ambiguous rejection"),
"HTTP 400: ambiguous rejection (WWW-Authenticate: Bearer)",
),
(
400,
"Bad Request: Unsupported protocol version (supported versions: 2025-06-18, 2099-01-01)",
"application/json",
),
(
400,
"Bad Request: Unsupported protocol version (supported versions: 2025-06-18, 2099-01-01)",
"text/plain",
),
(
400,
"Bad Request: Unsupported protocol version (supported versions: 2024-10-07)",
"application/json",
),
(
200,
"Bad Request: No valid session ID provided",
"application/json",
ResponseTemplate::new(400).set_body_json(json!({"error": {"code": -32021}})),
"-32021",
),
] {
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path("/mcp"))
.respond_with(move |request: &Request| {
let body: Value = request.body_json().expect("valid JSON-RPC request");
assert_eq!(body["method"], "server/discover");
ResponseTemplate::new(status).set_body_raw(
serde_json::to_vec(&json!({
"jsonrpc": "2.0",
"id": null,
"error": {"code": -32000, "message": message},
}))
.expect("legacy discovery error serializes"),
content_type,
)
})
.respond_with(rejection)
.expect(1)
.mount(&server)
.await;
let client = create_client(&server, McpProtocolMode::V20260728).await?;
let error = initialize_client(&client).await.unwrap_err();
assert!(format!("{error:#}").contains(diagnostic), "{error:#}");
client.shutdown().await;
}
Ok(())
}
#[tokio::test]
async fn rejection_after_modern_version_offer_stops_discovery() -> anyhow::Result<()> {
for (status, method_not_found) in [(400, false), (400, true), (200, true), (404, false)] {
let server = MockServer::start().await;
Mock::given(method("POST"))
.respond_with(|request: &Request| {
let body: Value = request.body_json().unwrap();
ResponseTemplate::new(400).set_body_json(json!({
"jsonrpc": "2.0", "id": body["id"],
"error": {"code": -32022, "message": "Unsupported protocol version: 2026-07-28",
"data": {"supported": [MODERN_VERSION]}},
}))
})
.up_to_n_times(1)
.mount(&server)
.await;
Mock::given(method("POST"))
.respond_with(move |request: &Request| {
let body: Value = request.body_json().unwrap();
if method_not_found {
ResponseTemplate::new(status).set_body_json(json!({
"jsonrpc": "2.0", "id": body["id"],
"error": {"code": -32601, "message": "second probe failed"},
}))
} else {
ResponseTemplate::new(status).set_body_string("second probe failed")
}
})
.mount(&server)
.await;
let client = create_client(&server, McpProtocolMode::V20260728).await?;
let error = initialize_client(&client).await.unwrap_err();
assert!(
initialize_client(&client).await.is_err(),
"unproven legacy downgrade must fail (HTTP {status}, {message})"
format!("{error:#}").contains("second probe failed"),
"{error:#}"
);
let methods: Vec<_> = server
.received_requests()
.await
.unwrap()
.iter()
.map(|r| r.body_json::<Value>().unwrap()["method"].clone())
.collect();
assert_eq!(methods, ["server/discover", "server/discover"]);
client.shutdown().await;
}
Ok(())
@@ -1426,10 +1477,8 @@ async fn modern_discovery_rejects_non_legacy_http_prevalidation_errors() -> anyh
(400, -32022, None, "application/json"),
(400, -32021, None, "application/json"),
(400, -32020, None, "application/json"),
(400, -32601, None, "application/json"),
(400, -32602, None, "application/json"),
(400, -32020, None, "text/plain"),
(400, -32000, Some("unrelated-request"), "application/json"),
(400, -32022, Some("unrelated-request"), "application/json"),
(401, -32000, None, "application/json"),
(403, -32000, None, "application/json"),
(200, -32000, None, "application/json"),
@@ -1504,7 +1553,7 @@ async fn modern_mode_falls_back_for_plain_404_and_405_discovery_responses() -> a
#[tokio::test]
async fn modern_discovery_rejection_does_not_downgrade_to_legacy() -> anyhow::Result<()> {
for (status, error_code) in [(400, -32602), (403, -32021), (200, -32020)] {
for (status, error_code) in [(400, -32020), (403, -32021), (200, -32020)] {
let server = MockServer::start().await;
Mock::given(method("POST"))