This is an automated email from the ASF dual-hosted git repository.
jamesnetherton pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel-quarkus.git
The following commit(s) were added to refs/heads/main by this push:
new f432a6274a2 Fixes #9522. mcp-server: test and document MCP protocol
version 2026-07-28
f432a6274a2 is described below
commit f432a6274a282fb576d844c217b8492359d8e969
Author: Federico Mariani <[email protected]>
AuthorDate: Thu Nov 19 08:09:31 2026 +0100
Fixes #9522. mcp-server: test and document MCP protocol version 2026-07-28
quarkus-mcp-server serves clients of MCP protocol version 2026-07-28
without a
session, next to the clients that open with initialize, on the same
endpoint.
Add McpServerStatelessTest (an McpAssured stateless client and a raw request
that creates no session) with its native McpServerStatelessIT, disabled on
main
like McpServerIT until #9362, and document the two kinds of clients.
---
.../pages/reference/extensions/mcp-server.adoc | 17 +++
.../mcp-server/runtime/src/main/doc/usage.adoc | 16 +++
.../mcp/server/it/McpServerStatelessIT.java | 26 +++++
.../mcp/server/it/McpServerStatelessTest.java | 130 +++++++++++++++++++++
4 files changed, 189 insertions(+)
diff --git a/docs/modules/ROOT/pages/reference/extensions/mcp-server.adoc
b/docs/modules/ROOT/pages/reference/extensions/mcp-server.adoc
index c405475512e..43bc541badf 100644
--- a/docs/modules/ROOT/pages/reference/extensions/mcp-server.adoc
+++ b/docs/modules/ROOT/pages/reference/extensions/mcp-server.adoc
@@ -192,6 +192,23 @@ The tools are served over streamable HTTP only. The stdio
transport, used
by MCP clients that launch the server as a subprocess, is not supported by
this extension.
+[id="extensions-mcp-server-usage-mcp-protocol-versions"]
+=== MCP protocol versions
+
+The quarkus-mcp-server extension serves two kinds of MCP clients on the same
+endpoint, and the Camel routes reach both without any Camel configuration:
+
+* clients of the protocol versions that open with an `initialize` handshake
+ (2025-11-25 and earlier) get a session, kept in memory by the application;
+* clients of protocol version 2026-07-28 have no session: each request carries
+ its protocol version and is served on its own, so such a client keeps working
+ when the application restarts, and any instance can answer its requests.
+ They are told about changed tool or resource lists through a
+ `subscriptions/listen` request.
+
+Clients that open with `initialize` always get a session; serving them without
+one is not offered by this extension.
+
[id="extensions-mcp-server-usage-mixing-with-quarkus-mcp-server-annotated-tools"]
=== Mixing with quarkus-mcp-server annotated tools
diff --git a/extensions/mcp-server/runtime/src/main/doc/usage.adoc
b/extensions/mcp-server/runtime/src/main/doc/usage.adoc
index 9feba283c11..a0b45c4efc1 100644
--- a/extensions/mcp-server/runtime/src/main/doc/usage.adoc
+++ b/extensions/mcp-server/runtime/src/main/doc/usage.adoc
@@ -126,6 +126,22 @@ The tools are served over streamable HTTP only. The stdio
transport, used
by MCP clients that launch the server as a subprocess, is not supported by
this extension.
+=== MCP protocol versions
+
+The quarkus-mcp-server extension serves two kinds of MCP clients on the same
+endpoint, and the Camel routes reach both without any Camel configuration:
+
+* clients of the protocol versions that open with an `initialize` handshake
+ (2025-11-25 and earlier) get a session, kept in memory by the application;
+* clients of protocol version 2026-07-28 have no session: each request carries
+ its protocol version and is served on its own, so such a client keeps working
+ when the application restarts, and any instance can answer its requests.
+ They are told about changed tool or resource lists through a
+ `subscriptions/listen` request.
+
+Clients that open with `initialize` always get a session; serving them without
+one is not offered by this extension.
+
=== Mixing with quarkus-mcp-server annotated tools
Camel tools coexist with tools defined natively with quarkus-mcp-server —
diff --git
a/integration-tests/mcp-server/src/test/java/org/apache/camel/quarkus/component/mcp/server/it/McpServerStatelessIT.java
b/integration-tests/mcp-server/src/test/java/org/apache/camel/quarkus/component/mcp/server/it/McpServerStatelessIT.java
new file mode 100644
index 00000000000..329707b8a12
--- /dev/null
+++
b/integration-tests/mcp-server/src/test/java/org/apache/camel/quarkus/component/mcp/server/it/McpServerStatelessIT.java
@@ -0,0 +1,26 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.camel.quarkus.component.mcp.server.it;
+
+import io.quarkus.test.junit.QuarkusIntegrationTest;
+import org.junit.jupiter.api.Disabled;
+
+@Disabled("https://github.com/apache/camel-quarkus/issues/9362")
+@QuarkusIntegrationTest
+class McpServerStatelessIT extends McpServerStatelessTest {
+
+}
diff --git
a/integration-tests/mcp-server/src/test/java/org/apache/camel/quarkus/component/mcp/server/it/McpServerStatelessTest.java
b/integration-tests/mcp-server/src/test/java/org/apache/camel/quarkus/component/mcp/server/it/McpServerStatelessTest.java
new file mode 100644
index 00000000000..415b87e8f06
--- /dev/null
+++
b/integration-tests/mcp-server/src/test/java/org/apache/camel/quarkus/component/mcp/server/it/McpServerStatelessTest.java
@@ -0,0 +1,130 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.camel.quarkus.component.mcp.server.it;
+
+import java.net.URI;
+import java.util.Map;
+import java.util.stream.Collectors;
+
+import io.quarkiverse.mcp.server.TextContent;
+import io.quarkiverse.mcp.server.TextResourceContents;
+import io.quarkiverse.mcp.server.test.McpAssured;
+import io.quarkiverse.mcp.server.test.McpAssured.McpStreamableTestClient;
+import io.quarkiverse.mcp.server.test.McpAssured.ToolInfo;
+import io.quarkus.test.junit.QuarkusTest;
+import io.restassured.RestAssured;
+import io.restassured.http.ContentType;
+import org.eclipse.microprofile.config.ConfigProvider;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.hamcrest.Matchers.containsString;
+
+/**
+ * Camel ai-tool and ai-resource routes served to a client of MCP protocol
version 2026-07-28 (CAMEL-27145): the
+ * quarkus-mcp-server extension serves that stateless protocol next to the
protocol versions with sessions, on the same
+ * endpoint, so the Camel routes reach both kinds of client without any Camel
configuration.
+ */
+@QuarkusTest
+class McpServerStatelessTest {
+
+ private McpStreamableTestClient client;
+
+ private McpStreamableTestClient client() {
+ if (client == null) {
+ client = McpAssured.newStreamableClient()
+
.setBaseUri(URI.create("http://localhost:%d".formatted(testPort())))
+ .setStateless()
+ .build()
+ .connect();
+ }
+ return client;
+ }
+
+ private static int testPort() {
+ return ConfigProvider.getConfig().getValue("quarkus.http.test-port",
Integer.class);
+ }
+
+ @AfterEach
+ void closeClient() {
+ if (client != null) {
+ client.disconnect();
+ client = null;
+ }
+ }
+
+ @Test
+ void testStatelessClientHasNoSession() {
+ assertThat(client().mcpSessionId()).isNull();
+ }
+
+ @Test
+ void testListToolsExposesOnlySelectedTags() {
+ client().when()
+ .toolsList(page ->
assertThat(page.tools().stream().map(ToolInfo::name).toList())
+ .contains("say_hello", "create_order")
+ .doesNotContain("hidden_tool", "other_tool"))
+ .thenAssertResults();
+ }
+
+ @Test
+ void testCallTool() {
+ client().when()
+ .toolsCall("say_hello", Map.of("name", "Camel"), response -> {
+ assertThat(response.isError()).isFalse();
+ assertThat(response.content().stream()
+ .filter(TextContent.class::isInstance)
+ .map(content -> ((TextContent) content).text())
+ .collect(Collectors.joining())).isEqualTo("Hello
Camel");
+ })
+ .thenAssertResults();
+ }
+
+ @Test
+ void testReadResource() {
+ client().when()
+ .resourcesRead("camel:///config/app.json", response -> {
+ TextResourceContents contents =
response.contents().get(0).asText();
+
assertThat(contents.mimeType()).isEqualTo("application/json");
+
assertThat(contents.text()).isEqualTo("{\"env\":\"test\"}");
+ })
+ .thenAssertResults();
+ }
+
+ @Test
+ void testRequestWithoutHandshakeCreatesNoSession() {
+ // a raw request of protocol version 2026-07-28: no initialize before
it, and no session after it
+ RestAssured.given()
+ .contentType(ContentType.JSON)
+ .accept("application/json, text/event-stream")
+ .header("MCP-Protocol-Version", "2026-07-28")
+ .header("Mcp-Method", "tools/call")
+ .header("Mcp-Name", "say_hello")
+ .body("""
+
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"say_hello",
+ "arguments":{"name":"stateless"},"_meta":{
+ "io.modelcontextprotocol/protocolVersion":"2026-07-28",
+
"io.modelcontextprotocol/clientInfo":{"name":"test","version":"1"},
+ "io.modelcontextprotocol/clientCapabilities":{}}}}""")
+ .post("http://localhost:%d/mcp".formatted(testPort()))
+ .then()
+ .statusCode(200)
+ .header("Mcp-Session-Id", (String) null)
+ .body(containsString("Hello stateless"));
+ }
+}