Skip to content

CAMEL-27145: camel-mcp-server - serve MCP protocol version 2026-07-28, and optionally without sessions - #30343

Merged
Croway merged 2 commits into
apache:mainfrom
Croway:CAMEL-27145-mcp-stateless
Nov 18, 2026
Merged

Croway merged 2 commits into
apache:mainfrom
Croway:CAMEL-27145-mcp-stateless

Conversation

@Croway

@Croway Croway commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

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

Option Values Effect
camel.server.mcp-protocol-era dual (default), legacy, modern dual serves, on the same endpoint, the protocol versions that open with initialize (with a session, as before) and MCP protocol version 2026-07-28 (no session). legacy behaves as before 4.24; modern serves only 2026-07-28.
camel.server.mcp-stateless false (default), true Serves the clients that open with initialize without a session (no Mcp-Session-Id), as the streamable HTTP transport allows since 2025-03-26. 2026-07-28 clients never get a session.
  • With dual, the protocol version in the request body decides; the MCP-Protocol-Version, Mcp-Method and Mcp-Name headers are checked against it (HTTP 400, -32020 on 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 with modern.
  • With legacy and mcp-stateless=true, a 2026-07-28 request gets HTTP 400 and -32600 naming the versions served, as with sessions, so a client that also speaks an older version falls back to initialize (a -32022 would identify a 2026-07-28 server).
  • Origin, Host and OAuth checks apply to every request. A request without a session does not need a token subject.
  • Serving 2026-07-28 is documented as a preview: it uses the io.modelcontextprotocol.modern server of the MCP Java SDK, which may still change before 3.0. mcp-protocol-era=legacy is the opt-out (upgrade guide entry).

How

  • MCP Java SDK 2.1.0 → 2.2.0 (the legacy API is unchanged; the SDK now notifies resources/list_changed on 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's HttpServletMcpTransport (header validation, JSON or SSE answers, subscriptions/listen, keep-alive) over repositories filled as ai-tool/ai-resource/ai-prompt routes start and stop.
  • VertxMcpStatelessServerTransport: Vert.x counterpart of the SDK's HttpServletStatelessServerTransport for mcp-stateless.
  • McpServerInfo gains protocolEra and stateless (compatibility constructors kept); engines that do not support them (Spring Boot, Quarkus, stdio) get a startup warning when they are set.
  • Docs: mcp-server.adoc "Protocol versions" and "Serving without sessions", Main options, upgrade guide.

Tests

  • Unit: camel-mcp-server-api 129, camel-mcp-server 173, 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 with mcp-stateless, OAuth on both paths, Main properties).
  • OfficialMcpModernConformanceIT and OfficialMcpDualConformanceIT (opt-in, -Dofficial-mcp-conformance): the @modelcontextprotocol/conformance 2026-07-28 requirements against mcp-protocol-era=modern and against the default dual, 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 existing OfficialMcpConformanceIT baseline was already stale on main (prompts-list, dns-rebinding-protection now pass) and is fixed here.
  • Manual, on Kubernetes (3 replicas, Service without session affinity, one connection per request):
    • default (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

Claude Code on behalf of Croway

…, 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
@github-actions

Copy link
Copy Markdown
Contributor

🌟 Thank you for your contribution to the Apache Camel project! 🌟
🤖 CI automation will test this PR automatically.

🐫 Apache Camel Committers, please review the following items:

  • First-time contributors require MANUAL approval for the GitHub Actions to run
  • You can use the command /component-test (camel-)component-name1 (camel-)component-name2.. to request a test from the test bot although they are normally detected and executed by CI.
  • You can label PRs using skip-tests and test-dependents to fine-tune the checks executed by this PR.
  • Build and test logs are available in the summary page. Only Apache Camel committers have access to the summary.

⚠️ Be careful when sharing logs. Review their contents before sharing them publicly.

@gnodet-bot gnodet-bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

🧪 CI tested the following changed modules:

  • catalog/camel-catalog
  • components/camel-ai/camel-mcp-server-api
  • components/camel-ai/camel-mcp-server
  • core/camel-main
  • docs
  • parent

ℹ️ Dependent modules were not tested because the total number of affected modules exceeded the threshold (50). Use the test-dependents label to force testing all dependents.

✅ POM dependency changes: targeted tests included

Changed properties: mcp-java-sdk-version

Modules affected by dependency changes (3)
  • :camel-openai
  • :camel-mcp-server
  • :camel-mcp-server-api

🔬 Scalpel shadow comparison — Scalpel: 80 of 729 tested, 1 compile-only — current: 79 all tested

Maveniverse 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)

⚠️ Modules only in Scalpel (1)
  • camel-jpa
Modules Scalpel would test (80)
  • camel-a2a ← depends on affected reactor module org.apache.camel:camel-platform-http-vertx
  • camel-as2 ← depends on affected reactor module org.apache.camel:camel-jetty
  • camel-aws-bedrock ← depends on affected reactor module org.apache.camel:camel-jq
  • camel-chaos ← depends on affected reactor module org.apache.camel:camel-netty-http
  • camel-cli-connector ← depends on affected reactor module org.apache.camel:camel-chaos
  • camel-cli-debug ← depends on affected reactor module org.apache.camel:camel-cli-connector
  • camel-clickup ← depends on affected reactor module org.apache.camel:camel-netty-http
  • camel-consul ← depends on affected reactor module org.apache.camel:camel-spring-main
  • camel-core-all ← depends on affected reactor module org.apache.camel:camel-main
  • camel-csv ← depends on affected reactor module org.apache.camel:camel-main
  • camel-fhir ← depends on affected reactor module org.apache.camel:camel-hl7
  • camel-groovy ← depends on affected reactor module org.apache.camel:camel-main
  • camel-hazelcast ← depends on affected reactor module org.apache.camel:camel-spring-main
  • camel-hl7 ← depends on affected reactor module org.apache.camel:camel-netty
  • camel-ibm-watsonx-ai ← depends on affected reactor module org.apache.camel:camel-vertx-websocket
  • camel-iso8583 ← depends on affected reactor module org.apache.camel:camel-groovy
  • camel-jackson ← depends on affected reactor module org.apache.camel:camel-main
  • camel-jackson-avro ← depends on affected reactor module org.apache.camel:camel-jackson
  • camel-jackson-protobuf ← depends on affected reactor module org.apache.camel:camel-jackson
  • camel-java-joor-dsl ← depends on affected reactor module org.apache.camel:camel-telegram
  • camel-jbang-mcp ← depends on affected reactor module org.apache.camel:camel-chaos
  • camel-jbang-plugin-mcp ← depends on affected reactor module org.apache.camel:camel-jbang-core
  • camel-jbang-plugin-tui ← depends on affected reactor module org.apache.camel:camel-chaos
  • camel-jbang-plugin-validate ← depends on affected reactor module org.apache.camel:camel-jbang-core
  • camel-jbang-run ← depends on affected reactor module org.apache.camel:camel-catalog
  • camel-jetty ← depends on affected reactor module org.apache.camel:camel-main
  • camel-jpa ← effective property camel.surefire.fork.additional-vmargs
  • camel-jq ← depends on affected reactor module org.apache.camel:camel-jackson
  • camel-jsonpath ← depends on affected reactor module org.apache.camel:camel-platform-http-vertx
  • camel-kamelet ← depends on affected reactor module org.apache.camel:camel-main
  • camel-kamelet-main-support ← depends on affected reactor module org.apache.camel:camel-main
  • camel-knative-http ← depends on affected reactor module org.apache.camel:camel-platform-http-vertx
  • camel-launcher-container ← depends on affected reactor module org.apache.camel:camel-launcher
  • camel-mail ← depends on affected reactor module org.apache.camel:camel-spring-main
  • camel-mail-microsoft-oauth ← depends on affected reactor module org.apache.camel:camel-mail
  • camel-main ← core/camel-main/src/generated/java/org/apache/camel/main/HttpServerConfigurationPropertiesConfigurer.java, core/camel-main/src/generated/resources/META-INF/camel-main-configuration-metadata.json, core/camel-main/src/generated/resources/org/apache/camel/main/main-options.properties, core/camel-main/src/main/docs/main.adoc, core/camel-main/src/main/java/org/apache/camel/main/HttpServerConfigurationProperties.java
  • camel-maven-plugin ← depends on affected reactor module org.apache.camel:camel-spring-main
  • camel-mcp-server ← components/camel-ai/camel-mcp-server/src/main/docs/mcp-server.adoc, components/camel-ai/camel-mcp-server/src/main/java/org/apache/camel/component/mcp/server/McpPromptSdkSupport.java, components/camel-ai/camel-mcp-server/src/main/java/org/apache/camel/component/mcp/server/main/DefaultMcpServerFactory.java, components/camel-ai/camel-mcp-server/src/main/java/org/apache/camel/component/mcp/server/stdio/StdioMcpServerEngine.java, components/camel-ai/camel-mcp-server/src/main/java/org/apache/camel/component/mcp/server/vertx/McpModernCatalog.java, components/camel-ai/camel-mcp-server/src/main/java/org/apache/camel/component/mcp/server/vertx/McpProtocolEraClassifier.java, components/camel-ai/camel-mcp-server/src/main/java/org/apache/camel/component/mcp/server/vertx/VertxMcpModernTransport.java, components/camel-ai/camel-mcp-server/src/main/java/org/apache/camel/component/mcp/server/vertx/VertxMcpServerEngine.java, components/camel-ai/camel-mcp-server/src/main/java/org/apache/camel/component/mcp/server/vertx/VertxMcpStatelessServerTransport.java, components/camel-ai/camel-mcp-server/src/main/java/org/apache/camel/component/mcp/server/vertx/VertxMcpStreamableServerTransportProvider.java, components/camel-ai/camel-mcp-server/src/test/java/org/apache/camel/component/mcp/server/main/McpServerMainOAuthModernTest.java, components/camel-ai/camel-mcp-server/src/test/java/org/apache/camel/component/mcp/server/main/McpServerMainOAuthStatelessTest.java, components/camel-ai/camel-mcp-server/src/test/java/org/apache/camel/component/mcp/server/main/McpServerMainOAuthTest.java, components/camel-ai/camel-mcp-server/src/test/java/org/apache/camel/component/mcp/server/main/McpServerMainProtocolEraTest.java, components/camel-ai/camel-mcp-server/src/test/java/org/apache/camel/component/mcp/server/vertx/McpProtocolEraClassifierTest.java, components/camel-ai/camel-mcp-server/src/test/java/org/apache/camel/component/mcp/server/vertx/VertxMcpModernClientTest.java, components/camel-ai/camel-mcp-server/src/test/java/org/apache/camel/component/mcp/server/vertx/VertxMcpProtocolEraTest.java, components/camel-ai/camel-mcp-server/src/test/java/org/apache/camel/component/mcp/server/vertx/VertxMcpRestartTest.java, components/camel-ai/camel-mcp-server/src/test/java/org/apache/camel/component/mcp/server/vertx/VertxMcpStatelessClientTest.java, components/camel-ai/camel-mcp-server/src/test/java/org/apache/camel/component/mcp/server/vertx/integration/OfficialMcpConformanceIT.java, components/camel-ai/camel-mcp-server/src/test/java/org/apache/camel/component/mcp/server/vertx/integration/OfficialMcpDualConformanceIT.java, components/camel-ai/camel-mcp-server/src/test/java/org/apache/camel/component/mcp/server/vertx/integration/OfficialMcpModernConformanceIT.java, components/camel-ai/camel-mcp-server/src/test/resources/expected-failures-2026-07-28.yaml, components/camel-ai/camel-mcp-server/src/test/resources/expected-failures.yaml, effective dep io.modelcontextprotocol.sdk:mcp-core, effective dep io.modelcontextprotocol.sdk:mcp-json-jackson3
  • camel-mcp-server-api ← components/camel-ai/camel-mcp-server-api/src/main/java/org/apache/camel/component/mcp/server/McpProtocolEra.java, components/camel-ai/camel-mcp-server-api/src/main/java/org/apache/camel/component/mcp/server/McpServerBridge.java, components/camel-ai/camel-mcp-server-api/src/main/java/org/apache/camel/component/mcp/server/McpServerConfiguration.java, components/camel-ai/camel-mcp-server-api/src/main/java/org/apache/camel/component/mcp/server/McpServerEngine.java, components/camel-ai/camel-mcp-server-api/src/main/java/org/apache/camel/component/mcp/server/McpServerInfo.java, components/camel-ai/camel-mcp-server-api/src/test/java/org/apache/camel/component/mcp/server/McpServerBridgeTest.java, effective dep io.modelcontextprotocol.sdk:mcp-core, effective dep io.modelcontextprotocol.sdk:mcp-json-jackson3
  • camel-mdc ← depends on affected reactor module org.apache.camel:camel-main
  • camel-micrometer-prometheus ← depends on affected reactor module org.apache.camel:camel-platform-http-main
  • camel-microprofile-health ← depends on affected reactor module org.apache.camel:camel-main
  • camel-netty ← depends on affected reactor module org.apache.camel:camel-main
  • camel-netty-http ← depends on affected reactor module org.apache.camel:camel-jetty
  • camel-oauth ← depends on affected reactor module org.apache.camel:camel-netty-http
  • camel-observability-services ← depends on affected reactor module org.apache.camel:camel-micrometer-prometheus
  • camel-once ← depends on affected reactor module org.apache.camel:camel-groovy
  • camel-openai ← effective dep io.modelcontextprotocol.sdk:mcp-core, effective dep io.modelcontextprotocol.sdk:mcp-json-jackson3
  • camel-openapi-validator ← depends on affected reactor module org.apache.camel:camel-platform-http-vertx
  • camel-platform-http-main ← depends on affected reactor module org.apache.camel:camel-platform-http-vertx
  • camel-platform-http-vertx ← depends on affected reactor module org.apache.camel:camel-rest-openapi
  • camel-plc4x ← depends on affected reactor module org.apache.camel:camel-main
  • camel-pubnub ← depends on affected reactor module org.apache.camel:camel-main
  • camel-quickfix ← depends on affected reactor module org.apache.camel:camel-jetty
  • camel-rest-openapi ← depends on affected reactor module org.apache.camel:camel-netty-http
  • camel-restdsl-openapi-plugin ← depends on affected reactor module org.apache.camel:camel-jetty
  • camel-salesforce ← depends on affected reactor module org.apache.camel:camel-csv
  • camel-salesforce-codegen ← depends on affected reactor module org.apache.camel:camel-salesforce
  • camel-salesforce-maven-plugin ← depends on affected reactor module org.apache.camel:camel-salesforce-codegen
  • camel-semantic ← depends on affected reactor module org.apache.camel:camel-main
  • camel-semantic-micrometer ← depends on affected reactor module org.apache.camel:camel-semantic
  • camel-semantic-openai ← depends on affected reactor module org.apache.camel:camel-openai
  • camel-semantic-typesafe-ai ← depends on affected reactor module org.apache.camel:camel-xml-io-dsl
  • camel-semantic-wolf-defender ← depends on affected reactor module org.apache.camel:camel-main
  • camel-spring-main ← depends on affected reactor module org.apache.camel:camel-main
  • camel-syslog ← depends on affected reactor module org.apache.camel:camel-netty
  • camel-telegram ← depends on affected reactor module org.apache.camel:camel-netty-http
  • camel-test-main-junit5 ← depends on affected reactor module org.apache.camel:camel-xml-io-dsl
  • camel-test-main-junit6 ← depends on affected reactor module org.apache.camel:camel-xml-io-dsl
  • camel-typesafe-ai ← depends on affected reactor module org.apache.camel:camel-xml-io-dsl
  • camel-vertx-websocket ← depends on affected reactor module org.apache.camel:camel-main
  • camel-webhook ← depends on affected reactor module org.apache.camel:camel-netty-http
  • camel-whatsapp ← depends on affected reactor module org.apache.camel:camel-netty-http
  • camel-xml-io-dsl ← depends on affected reactor module org.apache.camel:camel-kamelet
  • camel-xml-jaxb-dsl ← depends on affected reactor module org.apache.camel:camel-telegram
  • camel-xml-jaxb-dsl-test-definition ← depends on affected reactor module org.apache.camel:camel-telegram
  • camel-xml-jaxb-dsl-test-spring ← depends on affected reactor module org.apache.camel:camel-telegram
  • camel-yaml-dsl-validator ← depends on affected reactor module org.apache.camel:camel-catalog
  • camel-yaml-dsl-validator-maven-plugin ← depends on affected reactor module org.apache.camel:camel-yaml-dsl-validator
  • camel-zookeeper ← depends on affected reactor module org.apache.camel:camel-jetty
Modules with tests skipped (1)
  • camel-yaml-dsl-deserializers

ℹ️ Shadow mode — Scalpel observes but does not affect test execution. Learn more

⚠️ Some tests are disabled on GitHub Actions (@DisabledIfSystemProperty(named = "ci.env.name")) and require manual verification:

  • components/camel-ai/camel-mcp-server: 1 test(s) disabled on GitHub Actions
Build reactor — dependencies compiled but only changed modules were tested (6 modules, 2m 2s total)

Total reactor time: 2m 2s

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)

⚙️ View full build and test results

@Croway
Croway requested review from oscerd and ramu11 November 18, 2026 13:52

@davsclaus davsclaus left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

  1. Default-on preview. mcpProtocolEra defaults to dual, so every Camel Main / CLI user serves 2026-07-28 on the SDK's io.modelcontextprotocol.modern API, 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. Was legacy as 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.

  2. Gateway sentence in mcp-server.adoc ("A gateway in front of several instances may route on these headers."). In dual, a request with no _meta version and MCP-Protocol-Version: 2025-06-18 (or no header) is served as legacy, and its Mcp-Method / Mcp-Name headers are never compared with the body. The spec warns about this: intermediaries that enforce policy on the mirrored headers SHOULD check that MCP-Protocol-Version is a version that requires header-body validation, and reject otherwise. Please add that a gateway that routes or authorizes on Mcp-* headers must reject requests without MCP-Protocol-Version: 2026-07-28, or run with mcp-protocol-era = modern. The server itself behaves correctly.

  3. legacy + mcp-stateless = true answers a 2026-07-28 request with -32022, and the docs say the client then "falls back to initialize". 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 the initialize fallback. With a supported list of only 2025-xx versions, a modern-only client (e.g. the SDK 2.2.0 modern client) surfaces an error. legacy with 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: that supported list includes 2024-11-05, which the SDK's stateless transport does not serve.

  4. Optional: OfficialMcpModernConformanceIT runs only in modern; the default dual path is covered by VertxMcpProtocolEraTest but 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 oscerd left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
@Croway

Croway commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

Thanks @davsclaus and @oscerd. Changes in d1216f1:

1. dual as the default. It was a deliberate choice, made for these reasons:

  • A client that opens with initialize takes exactly the session path of legacy. In dual, the only extra step is reading the protocol version from the body, and only a request that carries 2026-07-28 takes the new path.
  • The clients that try 2026-07-28 first (the TypeScript and Python SDK clients, Claude Code) fall back to initialize when a server does not serve it. So legacy costs them nothing, and dual only changes what they choose.
  • quarkus-mcp-server does the same: since 2.0.1 (Camel Quarkus 3.40) it serves 2026-07-28 next to sessions with no option. Camel Main and Camel Quarkus behave the same way by default.
  • "Preview" is about the SDK's Java API, which may still change before SDK 3.0 and which we absorb inside camel-mcp-server. The protocol revision is published, and dual passes its conformance suite (point 4).
  • camel.server.mcp-protocol-era = legacy is the documented opt-out in the upgrade guide.

2. Gateway sentence. Agreed. mcp-server.adoc now says that the server compares Mcp-Method / Mcp-Name with the body only for 2026-07-28. A gateway that routes or authorizes on these headers must therefore reject requests without MCP-Protocol-Version: 2026-07-28, or the instances must run with mcp-protocol-era = modern.

3. legacy + mcp-stateless and -32022. Agreed. The 2026-07-28 Streamable HTTP "Backward Compatibility" section reads a recognised modern error as a 2026-07-28 server. Such a request now gets HTTP 400 and -32600 naming the versions the stateless transport serves (2025-03-26, 2025-06-18, 2025-11-25, so no more 2024-11-05). That is what legacy with sessions answers, so a client that also speaks an older version falls back to initialize. The doc sentence and the test are updated. This also makes oscerd's fallback point hold for every client, not only those that treat a -32022 listing only older versions as a fallback signal (the TypeScript client does).

4. Conformance on dual. Added OfficialMcpDualConformanceIT: the 2026-07-28 suite against the default dual, with the same baseline as modern. The existing OfficialMcpConformanceIT (older versions) already runs against the default, so dual is now covered by both suites. All three pass locally (-Dofficial-mcp-conformance).

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

@Croway
Croway requested review from davsclaus and oscerd November 18, 2026 14:43

@davsclaus davsclaus left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-reviewed d1216f1. All four points from my earlier review are addressed:

  • dual as the default: the reasoning makes sense, and legacy is 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 without MCP-Protocol-Version: 2026-07-28 (or the instances must run with modern).
  • Legacy + stateless: it now answers 400 / -32600 and lists only the versions the stateless transport serves (2024-11-05 is gone). The unused -32022 constant is removed, and the docs are updated.
  • OfficialMcpDualConformanceIT now runs the conformance suite on dual.

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.

@Croway
Croway merged commit 47abbbc into apache:main Nov 18, 2026
7 checks passed
@Croway Croway added the enhancement New feature or request label Nov 18, 2026
@Croway Croway self-assigned this Nov 18, 2026
@Croway Croway added this to the 4.24.0 milestone Nov 18, 2026
@Croway
Croway deleted the CAMEL-27145-mcp-stateless branch November 18, 2026 15:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants