Repository navigation
CAMEL-27145: camel-mcp-server - serve MCP protocol version 2026-07-28, and optionally without sessions - #30343
Conversation
…, and optionally without sessions The Camel Main / JBang MCP endpoint now serves, on the same /mcp, the protocol versions that open with an initialize handshake (with a session, as before) and MCP protocol version 2026-07-28 (no session), choosing for each request from the protocol version in its body; the headers are checked against the body. - camel.server.mcp-protocol-era = dual (default) | legacy | modern - camel.server.mcp-stateless = false (default) | true: serve the clients that open with initialize without a session, as the streamable HTTP transport allows - MCP Java SDK 2.2.0; 2026-07-28 is served through its io.modelcontextprotocol.modern server (preview), with a Vert.x transport next to the existing one - docs, upgrade guide, tests, and an opt-in conformance IT for 2026-07-28
|
🌟 Thank you for your contribution to the Apache Camel project! 🌟 🐫 Apache Camel Committers, please review the following items:
|
gnodet-bot
left a comment
There was a problem hiding this comment.
This PR adds support for the 2026-07-28 MCP protocol version and optional session-free operation — a significant feature addition. Two issues found, one of which is a correctness bug against the JSON-RPC 2.0 spec.
🐛 respondUnsupportedVersion() replies to JSON-RPC notifications — violates JSON-RPC 2.0 §4.2
McpProtocolEraClassifier.classify() returns Era.MODERN for any request carrying a 2026-07-28 protocol version header, regardless of message type. That includes notifications (messages with no id field, per JSON-RPC 2.0 §4).
In routePost(), when verdict.era() == MODERN and modernTransport == null (the DUAL/LEGACY era serving a 2026-07-28 client), respondUnsupportedVersion() is called unconditionally. That method constructs a JSON-RPC error response and sends HTTP 400 — even for notifications.
JSON-RPC 2.0 §4.2 is explicit: "A Notification is a Request object without an "id" member. […] The Server MUST NOT reply to a Notification."
Additionally, in respondUnsupportedVersion(), when id is null (notification case), the response omits the id field entirely via the if (id != null) guard. JSON-RPC 2.0 §5.1 requires that error responses include "id": null when the id cannot be determined — omitting it produces a non-compliant response.
Fix: Before calling respondUnsupportedVersion(), check whether the message is a notification (i.e. tree instanceof Map && !((Map<?,?>) tree).containsKey("id")) and return 202 silently in that case. Inside respondUnsupportedVersion(), use response.put("id", id) unconditionally (or explicitly response.put("id", null) when id == null).
ℹ️ Double-parse of request body in DUAL mode (informational)
In routePost() (DUAL/LEGACY era), the body string is parsed once at line 561 (jsonMapper.readValue(body, Object.class)) to produce tree for era classification, then passed raw to modernTransport.handle(body, ...) at line 582, which re-parses it via JsonRpc.deserializeMessage(jsonMapper, body) at VertxMcpModernTransport line 197.
This is a minor inefficiency — the already-parsed tree is discarded and the JSON is parsed a second time. Not a correctness issue. Possible fix: add a handle(Object parsedTree, ...) overload that accepts the pre-parsed object, or deserialise once and pass the JSONRPCMessage directly. This is entirely optional for this PR.
AI-assisted review.
|
🧪 CI tested the following changed modules:
✅ POM dependency changes: targeted tests included Changed properties: mcp-java-sdk-version Modules affected by dependency changes (3)
🔬 Scalpel shadow comparison — Scalpel: 80 of 729 tested, 1 compile-only — current: 79 all testedMaveniverse Scalpel detected 80 affected modules (current approach: 79). Changed properties: mcp-java-sdk-version Skip-tests mode would test 80 modules (8 direct + 0 downstream), skip tests for 1 (generated code, meta-modules)
|
| Module | Duration | Status |
|---|---|---|
| Camel :: Main | 42.9s | SUCCESS |
| Camel :: Catalog :: Camel Catalog | 29.9s | SUCCESS |
| Camel :: AI :: MCP Server API | 27.4s | SUCCESS |
| Camel :: Docs | 20.8s | SUCCESS |
| Camel :: Parent | 1.4s | SUCCESS |
| Camel :: AI :: MCP Server | n/a |
Top 20 slowest modules:
Camel :: Main(42.9s)Camel :: Catalog :: Camel Catalog(29.9s)Camel :: AI :: MCP Server API(27.4s)Camel :: Docs(20.8s)Camel :: Parent(1.4s)
davsclaus
left a comment
There was a problem hiding this comment.
Thanks, this is a thorough piece of work. The version choice follows the 2026-07-28 streamable HTTP spec as far as I can check: the _meta protocol version decides, a disagreeing header gets 400 / -32020, GET/DELETE get 405 in modern, and Mcp-Name is Base64-decoded before the comparison. 2025-xx clients in dual and legacy take the same session path as before. The tests cover each era, the SDK modern client, a restart in stateless mode and OAuth, and the upgrade guide documents the new default.
About gnodet-bot's two JSON-RPC "violation" comments: the 2026-07-28 transport spec says a server that cannot accept a notification MUST return an HTTP error status, and the body MAY be a JSON-RPC error response that has no id. So I don't think those need a change. The double parse is real but minor, and it also applies to every 2025-xx request in dual, so it fits a follow-up.
Points to look at:
-
Default-on preview.
mcpProtocolEradefaults todual, so every Camel Main / CLI user serves 2026-07-28 on the SDK'sio.modelcontextprotocol.modernAPI, which the docs call a preview that "may still change". Clients that try 2026-07-28 first switch to the new path without anyone choosing it. Waslegacyas the default (opt-in to the preview) considered? Either way is defensible with the upgrade-guide entry, but I'd like the choice to be deliberate. -
Gateway sentence in mcp-server.adoc ("A gateway in front of several instances may route on these headers."). In
dual, a request with no_metaversion andMCP-Protocol-Version: 2025-06-18(or no header) is served as legacy, and itsMcp-Method/Mcp-Nameheaders are never compared with the body. The spec warns about this: intermediaries that enforce policy on the mirrored headers SHOULD check thatMCP-Protocol-Versionis a version that requires header-body validation, and reject otherwise. Please add that a gateway that routes or authorizes onMcp-*headers must reject requests withoutMCP-Protocol-Version: 2026-07-28, or run withmcp-protocol-era = modern. The server itself behaves correctly. -
legacy+mcp-stateless = trueanswers a 2026-07-28 request with-32022, and the docs say the client then "falls back toinitialize". As I read the spec, a recognised modern error identifies a modern server and the client retries with another supported version instead of falling back; only a 4xx without a modern error body triggers theinitializefallback. With asupportedlist of only 2025-xx versions, a modern-only client (e.g. the SDK 2.2.0 modern client) surfaces an error.legacywith sessions answers with a plain 400, which does give the fallback. Answering the same way here, or softening the doc sentence, would fix it. Small detail: thatsupportedlist includes 2024-11-05, which the SDK's stateless transport does not serve. -
Optional:
OfficialMcpModernConformanceITruns only inmodern; the defaultdualpath is covered byVertxMcpProtocolEraTestbut has no conformance run.
Also, the commit has no Co-Authored-By trailer although the description says Claude Code; worth adding at squash-merge. And CAMEL-27145's summary ("stateless Streamable HTTP") is narrower than the PR, which also serves 2026-07-28 by default.
Reviewed with Claude Code on behalf of davsclaus. This review was generated by an AI agent and may contain inaccuracies; please verify all suggestions before applying.
oscerd
left a comment
There was a problem hiding this comment.
Went through this one carefully given it adds a second protocol era and a sessionless path to the streamable HTTP endpoint, and it holds up well. Notes from the review, with the parts I actually checked rather than took on trust.
The auth seam survives losing the session (my main concern). Modern (2026-07-28) and the opt-in legacy-stateless mode both drop the session, so the thing to verify was that they do not also drop authorization. They do not: in registerRoutes the POST route chains originHandler and oauthHandler ahead of dispatch(...) -> handlePost, so Origin/Host and OAuth are enforced before any era routing happens, for every path. McpServerMainOAuthModernTest and McpServerMainOAuthStatelessTest exercise that end to end. Dropping the session does not weaken the trust boundary, which is the point that mattered.
The new block() calls stay off the event loop. VertxMcpStatelessServerTransport.handle and the modern transport both block(). dispatch captures the event-loop context and offloads handlePost with executeBlocking(..., false), and every response is written back through that captured context via runOnContext. So the blocking resolution runs on a worker thread and only the write touches the event loop. That is the correct Vert.x offload, and it is consistent with how the existing session path already dispatched.
The classifier's confusion handling is the right shape. McpProtocolEraClassifier lets the body decide: the MCP-Protocol-Version header can never override a version carried in params._meta, and a disagreement is rejected with -32020 rather than silently picking one. initialize without a version is legacy, and an unknown version falls through to the modern server, which answers with the versions it supports. Letting the header decide only when the body is silent is the conservative reading, and it closes the obvious header/body mismatch gap.
Graceful degradation is spec-aligned. A legacy-stateless-only endpoint refuses a 2026-07-28 request with UnsupportedProtocolVersion (-32022) plus the supported-versions list instead of mis-serving it as legacy, which is exactly what lets a dual-speaking client (the Python SDK, per the ticket) fall back to initialize. GET and DELETE return 405 when sessionless, since there is no stream and no session to delete. Consistent throughout.
One design point for a second committer's eye, non-blocking. On Camel Main and JBang the default is dual, so the endpoint serves the 2026-07-28 preview out of the box. The upgrade guide is honest that this rides an MCP Java SDK API that may still change and documents camel.server.mcp-protocol-era = legacy to opt back out, and the blast radius is contained since legacy clients keep their sessions and only new-protocol clients take the new path. Whether a preview protocol should be on by default or opt-in until the SDK API settles is the one call here I would want a second opinion on before release; everything else is mechanical.
Conventions are in order: @since 4.24 on the new API types, the upgrade-guide entry is on main, the catalog, main-configuration-metadata and the generated configurer are regenerated and committed, and the SDK bump (2.1.0 to 2.2.0) is a minor one carried for the stateless API. Test coverage is broad: classifier unit tests, dual/modern/stateless Vert.x client tests, a restart test proving a modern client survives an application restart, and both the official MCP conformance IT and a new modern conformance IT with its own expected-failures file.
No blockers from me.
Claude Code on behalf of oscerd
…tateless endpoint, gateway note, dual conformance run - With mcp-protocol-era=legacy and mcp-stateless=true, a request of 2026-07-28 is answered with HTTP 400 and an Invalid Request error naming the versions served, as the legacy era with sessions does. The UnsupportedProtocolVersion error (-32022) answered before identifies a server of 2026-07-28, so a client following the specification would not fall back to initialize; it also listed 2024-11-05, which the stateless transport does not serve. - mcp-server.adoc: the server compares the Mcp-Method and Mcp-Name headers with the body only for 2026-07-28, so a gateway that routes or authorizes on them must reject the other requests, or run with mcp-protocol-era=modern. - OfficialMcpDualConformanceIT runs the 2026-07-28 conformance suite against the default dual era.
|
Thanks @davsclaus and @oscerd. Changes in d1216f1: 1.
2. Gateway sentence. Agreed. 3. 4. Conformance on 6. JIRA summary. CAMEL-27145 is now "camel-mcp-server - serve MCP protocol version 2026-07-28, and optionally without sessions". The PR description is updated. Claude Code on behalf of Croway |
davsclaus
left a comment
There was a problem hiding this comment.
Re-reviewed d1216f1. All four points from my earlier review are addressed:
dualas the default: the reasoning makes sense, andlegacyis the documented opt-out.- Gateway sentence (
mcp-server.adoc): it now says headers are compared with the body only for 2026-07-28, and that a gateway must reject requests withoutMCP-Protocol-Version: 2026-07-28(or the instances must run withmodern). - Legacy + stateless: it now answers 400 /
-32600and lists only the versions the stateless transport serves (2024-11-05 is gone). The unused-32022constant is removed, and the docs are updated. OfficialMcpDualConformanceITnow runs the conformance suite ondual.
The three gnodet-bot threads are answered by the Streamable HTTP rule (an error body with no id is allowed, and VertxMcpProtocolEraTest asserts the notification cases). The second parse is deliberate, so it can wait for a follow-up. I resolved the three threads.
Small note for the squash-merge: the commits have no AI Co-Authored-By trailer, and the merge can add it.
LGTM.
Claude Code on behalf of davsclaus. This review was generated by an AI agent and may contain inaccuracies; please verify all suggestions before applying.
CAMEL-27145: the Camel Main / JBang MCP endpoint (
/mcp, Vert.x engine) can now be served without sessions, so it keeps working across restarts and behind several instances without session affinity.What users get
camel.server.mcp-protocol-eradual(default),legacy,moderndualserves, on the same endpoint, the protocol versions that open withinitialize(with a session, as before) and MCP protocol version 2026-07-28 (no session).legacybehaves as before 4.24;modernserves only 2026-07-28.camel.server.mcp-statelessfalse(default),trueinitializewithout a session (noMcp-Session-Id), as the streamable HTTP transport allows since 2025-03-26. 2026-07-28 clients never get a session.dual, the protocol version in the request body decides; theMCP-Protocol-Version,Mcp-MethodandMcp-Nameheaders are checked against it (HTTP 400,-32020on mismatch). A request is never served under the other protocol's rules. The headers are compared with the body only for 2026-07-28, so the docs tell a gateway that routes or authorizes on them to reject the other requests, or to run withmodern.legacyandmcp-stateless=true, a 2026-07-28 request gets HTTP 400 and-32600naming the versions served, as with sessions, so a client that also speaks an older version falls back toinitialize(a-32022would identify a 2026-07-28 server).io.modelcontextprotocol.modernserver of the MCP Java SDK, which may still change before 3.0.mcp-protocol-era=legacyis the opt-out (upgrade guide entry).How
resources/list_changedon template removal, so Camel's workaround is removed from both engines).McpProtocolEraClassifier: decides the era from the body, cross-checks the header.VertxMcpModernTransport+McpModernCatalog: Vert.x counterpart of the SDK'sHttpServletMcpTransport(header validation, JSON or SSE answers,subscriptions/listen, keep-alive) over repositories filled asai-tool/ai-resource/ai-promptroutes start and stop.VertxMcpStatelessServerTransport: Vert.x counterpart of the SDK'sHttpServletStatelessServerTransportformcp-stateless.McpServerInfogainsprotocolEraandstateless(compatibility constructors kept); engines that do not support them (Spring Boot, Quarkus, stdio) get a startup warning when they are set.mcp-server.adoc"Protocol versions" and "Serving without sessions", Main options, upgrade guide.Tests
camel-mcp-server-api129,camel-mcp-server173, green locally (new: classifier, protocol eras over HTTP, the SDK 2026-07-28 client for tools/resources/templates/prompts/subscriptions/listen, the SDK legacy client across a server restart withmcp-stateless, OAuth on both paths, Main properties).OfficialMcpModernConformanceITandOfficialMcpDualConformanceIT(opt-in,-Dofficial-mcp-conformance): the@modelcontextprotocol/conformance2026-07-28 requirements againstmcp-protocol-era=modernand against the defaultdual, with the same baseline. Every transport, header and version check passes; the baseline lists features Camel does not offer on any version (multi round-trip input, tasks, completions, rich tool content). The existingOfficialMcpConformanceITbaseline was already stale onmain(prompts-list,dns-rebinding-protectionnow pass) and is fixed here.dual): legacy client with a session 4/12 (only its pod), 0/12 after a rolling restart; 2026-07-28 client 12/12 across pods, and after the restart;mcp-stateless=true: legacy client 12/12 across pods and 12/12 after the restart without re-initializing.Related
spring.ai.mcp.server.protocol=STATELESS.Claude Code on behalf of Croway