Merge pull request #109317 from ShaunaDiaz/OSDOCS-18126

OSDOCS-18128: adds intro and arch to MCP gateway

Author: ShaunaDiaz

_topic_maps/_topic_map.yml

@@ -36,8 +36,6 @@ Distros: rhcl
 Topics:
 - Name: About the MCP gateway
   File: mcp-gateway-introduction
-- Name: MCP gateway architecture
-  File: mcp-gateway-architecture
 ---
 Name: Release notes
 Dir: release_notes

mcp_gateway_discover/mcp-gateway-architecture.adoc

@@ -1,8 +1,18 @@
 :_mod-docs-content-type: ASSEMBLY
 include::_attributes/attributes.adoc[]
 [id="mcp-gateway-introduction"]
-= Introduction to {mcpg}
+= Introduction to the {mcpg}
 :context: mcp-gateway-introduction
 
 [role="_abstract"]
-FPO assembly
+You can centralize and manage the connectivity for your agentic AI applications that access your Model Context Protocol (MCP) servers by using the MCP gateway.
+
+:FeatureName: MCP gateway
+
+include::snippets/technology-preview.adoc[leveloffset=+1]
+
+include::modules/con-about-mcp-gateway.adoc[leveloffset=+1]
+
+include::modules/con-mcp-gateway-architecture.adoc[leveloffset=+1]
+
+include::modules/con-mcp-gateway-arch-components.adoc[leveloffset=+2]

mcp_gateway_discover/mcp-gateway-introduction.adoc

@@ -0,0 +1,21 @@
+
+// Module included in the following assemblies:
+//
+// *mcp_gateway_discover/about-mcp-gateway.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="con-about-mcp-gateway_{context}"]
+= About the {mcpg}
+
+[role="_abstract"]
+You can focus on your agentic AI systems without building networking into your application code by using the Model Context Protocol (MCP) gateway. Application teams and platform engineers can operate and collaborate to expose MCP servers with the MCP gateway as secure and protected services just as you do with existing RESTFul based APIs.
+
+For example, you can achieve the following goals by using the MCP gateway to connect your MCP servers:
+
+* Aggregate MCP servers behind a single endpoint.
+* Grow your agentic AI applications at scale, keeping connectivity outside of application development.
+* Manage access to and the security of AI tools and MCP servers.
+
+The {prodname} implementation of the MCP gateway extends the benefits of the Envoy proxy server to your customized AI agent systems.
+
+The Envoy proxy server handles traffic from agentic AI clients to your backend MCP servers at the gateway ingress. Envoy is a conformance-tested implementation of the Kubernetes Gateway API. By using the MCP gateway, you can extend the capabilities of Envoy without the complexity of manual configuration.

modules/con-about-mcp-gateway.adoc

@@ -0,0 +1,41 @@
+// Module included in the following assemblies:
+//
+// *mcp_gateway_discover/about-mcp-gateway.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="con-mcp-gateway-arch-components_{context}"]
+= {mcpg} architectural components
+
+[role="_abstract"]
+The MCP gateway architecture consists of three components that manage connectivity: the router, broker, and controller.
+
+MCP router::
+The MCP router is an Envoy-focused `ext_proc` component that is capable of parsing the MCP protocol. When `ext_proc` parses the MCP Protocol, the router uses the protocol to set headers to force the correct routing of the request to the correct MCP server.
++
+The MCP router component is responsible for the following activities:
+
+* Parsing and validating the `JSON-RPC` request object, which is the MCP message body
+* Setting the key request headers, `:authority`, `:path`, `x-mcp-method`, `x-mcp-servername`, `x-mcp-toolname`, and `mcp-session-id`
+* Watching for `404` responses from MCP servers and invalidating the session store
+* Handling session initialization and storage on behalf of a requesting MCP client during a tools call request
+
+MCP broker::
+The MCP broker manages the complexity of connecting to multiple AI services simultaneously for you. The broker component aggregates multiple backend MCP servers and presents them as a unified MCP server to clients. This means that your MCP clients or applications do not have to manage a large set of MCP servers and configurations for each server.
++
+The MCP broker component is a backend service that acts as a default MCP server backend for the `/mcp` endpoint. For example, the broker does the following activities:
+
+* Handles the handshake, `init`.
+* Discovers tools from connected MCP servers and aggregates them into a unified list. Validates that discovered MCP servers meet minimum protocol version and capabilities before including their tools in the list.
+* Listens for updates and can change its state so that the agentic AI always has the latest information.
+* Handles notifications sent through whichever backend MCP server it is connected to, for example, `notifications/tools/list_changed`.
+* Handles notification requests from clients and MCP servers by proxying from the MCP server notification to registered clients.
+
+MCP discovery controller::
+The MCP discovery controller is a Kubernetes-based controller that watches for changes to custom resources (CRs). The MCP discovery controller uses CRs to configure the MCP gateway and register MCP servers. The CRs are then turned into a configuration that is consumed by the MCP gateway so that it can route and present the tools from the registered MCP server to the client.
++
+The MCP discovery controller component is responsible for the following activities:
+
+* Watching `MCPServerRegistration` CRs
+* Maintaining a configuration from both `HTTPRoute` and `MCPServerRegistration` CRs
+* Updating the MCP broker and MCP router config secret based on discovered `MCPServerRegistration` CRs and the `HTTPRoutes` they target
+* Reporting the status of `MCPServerRegistrations` CRs

modules/con-mcp-gateway-arch-components.adoc

@@ -0,0 +1,18 @@
+// Module included in the following assemblies:
+//
+// *mcp_gateway_discover/about-mcp-gateway.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="mcp-gateway-architecture_{context}"]
+= {mcpg} architecture
+
+[role="_abstract"]
+The architecture of the Model Context Protocol (MCP) gateway builds on top of the routing capabilities of the Envoy proxy with capabilities to handle the MCP.
+
+Design considerations include the following high-level goals:
+
+* The MCP gateway must work with the Gateway API as a routing configuration.
+* Envoy controls routing and traffic as the implementation of the Gateway API.
+* The MCP gateway focuses on the MCP Protocol.
+* Use Istio as the gateway control plane in {ocp} with the Gateway API.
+* {prodname} is used for other key features, such as `AuthPolicy` and rate-limiting custom resources.