diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index c2e64a48138..488a87d922e 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -95,6 +95,8 @@ Topics: File: mcp-gateway-revoke-tool-access - Name: Use credentials to access external APIs File: mcp-gateway-vault +- Name: Multi-protocol support for the MCP gateway + File: mcp-gateway-multi-protocol-support --- Name: Develop APIs with the web console Dir: develop diff --git a/mcp_gateway_config/mcp-gateway-multi-protocol-support.adoc b/mcp_gateway_config/mcp-gateway-multi-protocol-support.adoc new file mode 100644 index 00000000000..93f69f7bc4b --- /dev/null +++ b/mcp_gateway_config/mcp-gateway-multi-protocol-support.adoc @@ -0,0 +1,28 @@ +:_mod-docs-content-type: ASSEMBLY +include::_attributes/attributes.adoc[] +[id="mcp-gateway-multi-protocol-support"] += Multi-protocol support for the {mcpg} +:context: mcp-gateway-multi-protocol-support + +toc::[] + +[role="_abstract"] +You can use the {mcpg} to serve both stateful and stateless MCP protocol versions from a single instance. Clients negotiate their preferred version automatically. + +include::modules/con-mcp-gateway-multi-protocol-support.adoc[leveloffset=+1] + +include::modules/proc-mcp-gateway-verify-protocol-support.adoc[leveloffset=+1] + +include::modules/ref-mcp-gateway-protocol-behavior-differences.adoc[leveloffset=+1] + +include::modules/proc-mcp-gateway-set-protocol-routes.adoc[leveloffset=+1] + +include::modules/ref-mcp-gateway-protocol-specific-routes.adoc[leveloffset=+1] + +[id="additional-resources_mcp-gateway-multi-protocol-support"] +[role="_additional-resources"] +== Additional resources + +* xref:../mcp_gateway_config/mcp-gateway-register-ext-mcp-servers.adoc#mcp-gateway-register-ext-mcp-servers[Register external MCP servers with the {mcpg}] +* xref:../mcp_gateway_config/mcp-gateway-authentication.adoc#mcp-gateway-authentication[Use authentication with {mcpg}] +* xref:../mcp_gateway_discover/mcp-gateway-introduction.adoc#mcp-gateway-introduction[Introduction to the {mcpg}] diff --git a/modules/con-mcp-gateway-multi-protocol-support.adoc b/modules/con-mcp-gateway-multi-protocol-support.adoc new file mode 100644 index 00000000000..0acc01b802e --- /dev/null +++ b/modules/con-mcp-gateway-multi-protocol-support.adoc @@ -0,0 +1,62 @@ +// Module included in the following assemblies: +// +// *mcp_gateway_config/mcp-gateway-multi-protocol-support.adoc + +:_mod-docs-content-type: CONCEPT +[id="con-mcp-gateway-multi-protocol-support_{context}"] += Understand multi-protocol support + +[role="_abstract"] +The {mcpg} can serve both the `2025-11-25`, stateful, and `2026-07-28`, stateless, Model Context Protocol (MCP) protocol versions from a single instance. + +The new stateless protocol has the following cloud-native pattern: + +* Round-robin load balancing: Because any container instance can handle any incoming request, you can horizontally scale your stateful MCP servers behind a plain round-robin load balancer. +* Serverless deployment: You can now run MCP servers as serverless functions on cloud platforms because there is no need for a persistent connection. +* Transparent failover: If a container crashes, the load balancer routes the next request to a healthy peer with zero session disruption. +* No Redis sessions: Because persistency and sticky sessions are no longer needed, you can remove Redis session storage. Database writes and reads on every single call are not required. + +Clients negotiate their preferred version automatically + +[id="con-mcp-gateway-multi-protocol-version-detection_{context}"] +== How version detection works + +When an MCP client SDK connects, the {mcpg} detects the MCP protocol version by using the following sequence: +//Q: is this really just an MCP client? +. The SDK client sends a `server/discover` request with a `MCP-Protocol-Version: 2026-07-28` header. +. The {mcpg} responds with `supportedVersions`, which is the union of all upstream MCP server protocol versions. +. If the client and the {mcpg} share a common version, the SDK negotiates the highest one. +. If the client does not send a `server/discover` request, the {mcpg} falls back to the `initialize` handshake with `2025-11-25`. This is typically the case for older SDKs. + +The following table shows how the {mcpg} negotiates the protocol version depending on the available backend MCP servers: + +.Protocol version negotiation +[cols="1,1,1",options="header"] +|=== +|Backend MCP server versions +|Supported protocol versions +|SDK negotiates + +|2025 +|2025-11-25 +|2025-11-25 + +|2026 +|2026-07-28 +|2026-07-28 + +|Both +|2025-11-25, 2026-07-28 +|2026-07-28 +|=== + +[id="con-mcp-gateway-multi-protocol-tool-visibility_{context}"] +== Tool visibility by protocol version + +The `tools/list` response returns only tools from the following protocol-compatible backends: + +* 2025-11-25 clients: Use tools from servers that negotiated `2025-11-25`, plus the `discover_tools` and `select_tools` meta-tools. + +* 2026-07-28 clients: Use tools from servers that negotiated `2026-07-28`, without `meta-tools`. + +`UserSpecificList` servers follow the same filtering. Per-user tools are only displayed from backends that match the client protocol version. diff --git a/modules/proc-mcp-gateway-set-protocol-routes.adoc b/modules/proc-mcp-gateway-set-protocol-routes.adoc new file mode 100644 index 00000000000..a44d129156a --- /dev/null +++ b/modules/proc-mcp-gateway-set-protocol-routes.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// *mcp_gateway_config/mcp-gateway-multi-protocol-support.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-mcp-gateway-set-protocol-specific-routes_{context}"] += Set MCP protocol-specific routes + +[role="_abstract"] +The {mcpg} exposes two endpoints on every Model Context Protocol (MCP) listener. You can use the default endpoint for automatic version negotiation, or the stateful endpoint to force the `2025-11-25` protocol version. + +* Use the `/mcp` default endpoint for most clients. The {mcpg} negotiates the correct version automatically. +* Use the `/mcp/stateful` endpoint when a `2026-07-28`-capable agent also needs access to `2025-11-25`-only tools. + +.Procedure + +* Configure an agent with two MCP server entries that point at the same gateway host by using the following example: ++ +[source,yaml] +---- +mcpServers: + gateway-default: + url: https://__/mcp + gateway-legacy: + url: https://__/mcp/stateful +---- ++ +* Replace with your MCP gateway `Gateway` object hostname. +* The default entry negotiates `2026-07-28` and shows stateless tools. The `/mcp/stateful` entry forces `2025-11-25` and shows stateful tools plus the `discover_tools` and `select_tools` meta-tools. diff --git a/modules/proc-mcp-gateway-verify-protocol-support.adoc b/modules/proc-mcp-gateway-verify-protocol-support.adoc new file mode 100644 index 00000000000..c73c1973cd4 --- /dev/null +++ b/modules/proc-mcp-gateway-verify-protocol-support.adoc @@ -0,0 +1,42 @@ +// Module included in the following assemblies: +// +// *mcp_gateway_config/mcp-gateway-multi-protocol-support.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-mcp-gateway-verify-protocol-support_{context}"] += Verify protocol support for the {mcpg} + +[role="_abstract"] +You can check which Model Context Protocol (MCP) protocol versions your {mcpg} instance advertises by sending a `server/discover` request. + +.Prerequisites + +* You have access to the {mcpg} endpoint. +* You installed the `jq` CLI tool. + +.Procedure + +. Check which protocol versions the {mcpg} advertises by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ curl -sS -X POST https://__/mcp \ + -H "Content-Type: application/json" \ + -H "Accept: application/json, text/event-stream" \ + -H "Mcp-Protocol-Version: 2026-07-28" \ + -d '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28"}}}' \ + | jq '.result.supportedVersions' +---- ++ +Replace `__` with the hostname of your {mcpg} instance. + +. Confirm that the output lists the expected protocol versions. For example: ++ +[source,text] +---- +[ + "2025-11-25", + "2026-07-28" +] +---- +//Q: what if it accepts only the older version? \ No newline at end of file diff --git a/modules/ref-mcp-gateway-protocol-behavior-differences.adoc b/modules/ref-mcp-gateway-protocol-behavior-differences.adoc new file mode 100644 index 00000000000..c138e6993bf --- /dev/null +++ b/modules/ref-mcp-gateway-protocol-behavior-differences.adoc @@ -0,0 +1,42 @@ +// Module included in the following assemblies: +// +// *mcp_gateway_config/mcp-gateway-multi-protocol-support.adoc + +:_mod-docs-content-type: REFERENCE +[id="ref-mcp-gateway-protocol-behavior-differences_{context}"] += Protocol behavior differences + +[role="_abstract"] +The stateful and stateless Model Context Protocol (MCP) protocol versions differ in how the {mcpg} handles routing, sessions, backend initialization, and response handling. + +.Behavior differences between protocol versions +[cols="1,1,1",options="header"] +|=== +|Behavior +|2025-11-25, stateful +|2026-07-28, stateless + +|Routing +|Body-parsed: JSON-RPC method and parameters +|Header-based: `Mcp-Method`, `Mcp-Name` + +|Sessions +|JWT-based `mcp-session-id` +|None + +|Backend initialization +|Hairpin initialization through the {mcpg} +|`server/discover` + +|Response handling +|Session ID rewriting, elicitation ID rewriting +|Pass-through + +|Header-body validation +|Not applicable +|Rejects mismatches between the `Mcp-Name` header and the body `params.name` + +|Meta-tools +|`discover_tools`, `select_tools` available +|Not available +|=== diff --git a/modules/ref-mcp-gateway-protocol-specific-routes.adoc b/modules/ref-mcp-gateway-protocol-specific-routes.adoc new file mode 100644 index 00000000000..3380d44b857 --- /dev/null +++ b/modules/ref-mcp-gateway-protocol-specific-routes.adoc @@ -0,0 +1,26 @@ +// Module included in the following assemblies: +// +// *mcp_gateway_config/mcp-gateway-multi-protocol-support.adoc + +:_mod-docs-content-type: REFERENCE +[id="ref-mcp-gateway-protocol-specific-routes_{context}"] += Protocol-specific routes + +[role="_abstract"] +The {mcpg} exposes two endpoints on every Model Context Protocol (MCP) listener. The broker `MCPHandler` serves these endpoints. You do not need to make any configurations or additional `HTTPRoute` objects. + +.MCP listener endpoints +[cols="1,1,2",options="header"] +|=== +|Endpoint +|Protocol +|Behavior + +|`/mcp` +|Auto-negotiated +|The `server/discover` method determines the version. Falls back to `initialize` for older SDKs. A `2026-07-28` SDK client that connects to `/mcp` negotiates `2026-07-28` by default. + +|`/mcp/stateful` +|Forces 2025-11-25 +|Session-based routing. The `discover_tools` and `select_tools` meta-tools are available. The `/mcp/stateful` route is available for agents that also need tools from `2025-11-25`-only backends. It forces `2025-11-25` negotiation regardless of the client capabilities. +|===