OSDOCS-18939: adds external MCP server registration to gateway docs

_attributes/attributes.adoc

@@ -20,7 +20,7 @@
 :ocp-min-version: 4.19
 :oc-first: pass:quotes[OpenShift CLI (`oc`)]
 
-:service-mesh: OpenShift Service Mesh
+:ossm: OpenShift Service Mesh
 :service-mesh-version: 3.2
 
 :cert-manager: cert-manager Operator for Red Hat OpenShift

_topic_maps/_topic_map.yml

@@ -75,8 +75,8 @@ Distros: rhcl
 Topics:
 - Name: Configuring the MCP gateway
   File: mcp-gateway-config-listener-route
-- Name: Register MCP servers
-  File: mcp-gateway-register-servers
+- Name: Registering external MCP servers
+  File: mcp-gateway-register-ext-mcp-servers
 - Name: Configuring authentication for the MCP gateway
   File: mcp-gateway-authz
 - Name: Configuring authorization for the MCP gateway

mcp_gateway_config/mcp-gateway-register-ext-mcp-servers.adoc

@@ -0,0 +1,22 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="mcp-gateway-register-ext-mcp-servers"]
+= Registering external MCP servers
+include::_attributes/attributes.adoc[]
+:context: mcp-gateway-register-ext-mcp-servers
+
+[role="_abstract"]
+To use external MCP servers with your MCP gateway, you must configure ingress, create routing resources, and register the server with the MCP gateway. As a best practice, you must also configure security rules.
+
+include::modules/proc-register-ext-mcp-server-ingress.adoc[leveloffset=+1]
+
+include::modules/proc-register-ext-mcp-server-tls.adoc[leveloffset=+1]
+
+include::modules/proc-register-ext-mcp-server-httproute.adoc[leveloffset=+1]
+
+include::modules/proc-register-ext-mcp-server-secret.adoc[leveloffset=+1]
+
+include::modules/proc-register-ext-mcp-server-authpolicy.adoc[leveloffset=+1]
+
+include::modules/proc-register-ext-mcp-server-mcpserverregistration.adoc[leveloffset=+1]
+
+include::modules/proc-register-ext-mcp-server-verify.adoc[leveloffset=+1]

modules/proc-register-ext-mcp-server-authpolicy.adoc

@@ -0,0 +1,66 @@
+// Module included in the following assemblies:
+//
+// *mcp_gateway_config/mcp-gateway-register-ext-mcp-servers.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="proc-register-ext-mcp-server-authpolicy_{context}"]
+= Creating an AuthPolicy for an external MCP server
+
+[role="_abstract"]
+To secure your use of an external MCP server, creating an `AuthPolicy` custom resource (CR) to authenticate your sessions is a best practice. The following example uses `Kuadrant/Authorino` for OAuth authentication and creates an `AuthPolicy` CR to handle authorization headers.
+
+[NOTE]
+====
+This step is required if you are using OAuth authentication for your external MCP server. If your external MCP server uses a simple API key, you can use a `credentialRef` in your `MCPServerRegistration` CR instead, and an `AuthPolicy` object is not needed.
+====
+
+.Prerequisites
+
+* You completed all of the installation and configuration steps for {mcpg}.
+* You have the information for the external MCP server you want to connect to.
+* You installed the {oc-first}.
+* You are using Istio for ingress control.
+* You created `ServiceEntry`, `DestinationRule`, and `HTTPRoute` objects.
+
+.Procedure
+
+. Create an `AuthPolicy` CR that handles authorization headers by using the following example:
++
+.Example AuthPolicy CR
+[source,yaml,subs="+quotes"]
+----
+apiVersion: kuadrant.io/v1
+kind: AuthPolicy
+metadata:
+  name: _<mcps_auth_policy>_
+  namespace: _<mcp_test>_
+spec:
+  targetRef:
+    group: gateway.networking.k8s.io
+    kind: HTTPRoute
+    name: _<mcp_external_server>_
+  rules:
+    response:
+      success:
+        headers:
+          authorization:
+            plain:
+              expression: 'request.headers["authorization"]'
+          x-mcp-api-key:
+            plain:
+              expression: 'request.headers["authorization"].split(" ")[1]'
+----
++
+* Replace the `metadata.name:` field value with the name you want to use. This approach uses service naming.
+* Replace the `metadata.namespace:` field value with the namespace you used in your `ServiceEntry` object.
+* Replace the `spec.name:` value with the name of your external MCP server route.
+* This `AuthPolicy` CR extracts the API key from the OAuth token and sets it as the `x-mcp-api-key` header.
+
+. Apply the CR by running the following command:
++
+[source,terminal,subs="+quotes"]
+----
+$ oc apply -f _<mcp_external_server_authpolicy.yaml>_
+----
++
+Replace `_<mcp_external_server_authpolicy.yaml>_` with the name of your CR.

modules/proc-register-ext-mcp-server-httproute.adoc

@@ -0,0 +1,71 @@
+// Module included in the following assemblies:
+//
+// *mcp_gateway_config/mcp-gateway-register-ext-mcp-servers.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="proc-register-ext-mcp-server-httproute_{context}"]
+= Creating an HTTPRoute for an external MCP server
+
+[role="_abstract"]
+To use an external MCP server, you must create an `HTTPRoute` custom resource (CR) that matches your internal hostname and routes to the external service by using Istio.
+
+.Prerequisites
+
+* You completed all of the installation and configuration steps for {mcpg}.
+* You have the information for the external MCP server you want to connect to.
+* You installed the {oc-first}.
+* You are using Istio for ingress control.
+* You created `ServiceEntry` and `DestinationRule` objects.
+
+.Procedure
+
+. Create a `HTTPRoute` CR that routes to the external service by using the following example:
++
+.Example HTTPRoute CR
+[source,yaml,subs="+quotes"]
+----
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+  name: _<mcp_external_server>_
+  namespace: _<mcp_test>_
+spec:
+  parentRefs:
+  - group: gateway.networking.k8s.io
+    kind: Gateway
+    name: _<mcp_gateway>_
+    namespace: _<gateway_system>_
+  hostnames:
+  - example.mcp.local
+  rules:
+  - matches:
+    - path:
+        type: PathPrefix
+        value: /mcp
+    filters:
+    - type: URLRewrite
+      urlRewrite:
+        hostname: _<api.externalhostname.com>_
+    backendRefs:
+    - name: _<api.example.com>_
+      kind: Hostname
+      group: networking.istio.io
+      port: 443
+----
++
+* Replace the `metadata.name:` field value with the name of your external MCP server.
+* Replace the `metadata.namespace:` field value with the namespace that the MCP server is in.
+* Set the `spec.parentRefs:` fields to match your MCP `Gateway` object.
+* The `spec.hostnames:` field value is your internal hostname. It must match your `*.mcp.local` `Gateway` CR value.
+* The `spec.rules.matches.path.value:` field value is your MCP gateway endpoint. In this example, `/mcp` is used.
+* Replace the value of `spec.rules.filters.urlRewrite.hostname:` with your external hostname.
+* Replace the `spec.rules.backendRefs.name:` field value with the host URL of the MCP server.
+
+. Apply the CR by running the following command:
++
+[source,terminal,subs="+quotes"]
+----
+$ oc apply -f _<mcp_external_server_httproute.yaml>_
+----
++
+Replace `_<mcp_external_server_httproute.yaml>_` with the name of your CR.

modules/proc-register-ext-mcp-server-ingress.adoc

@@ -0,0 +1,54 @@
+// Module included in the following assemblies:
+//
+// *mcp_gateway_config/mcp-gateway-register-ext-mcp-servers.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="proc-register-ext-mcp-server-serviceentry_{context}"]
+= Creating a ServiceEntry for an external MCP server
+
+[role="_abstract"]
+To register an external MCP server, you must first make sure that it has an ingress pathway by creating a `ServiceEntry` custom resource (CR) in your Istio deployment. {ocp} 4.19 and newer provides Istio through the Gateway API.
+
+.Prerequisites
+
+* You completed all of the installation and configuration steps for {mcpg}.
+* You have the information for the external MCP server you want to connect to.
+* You installed the {oc-first}.
+* You are using Istio for ingress control.
+
+.Procedure
+
+. Create a `ServiceEntry` CR that registers the external server in the Istio service registry by using the following template:
++
+.Example ServiceEntry CR
+[source,yaml,subs="+quotes"]
+----
+apiVersion: networking.istio.io/v1beta1
+kind: ServiceEntry
+metadata:
+  name: _<mcp_external_server>_
+  namespace: _<mcp_test>_
+spec:
+  hosts:
+  - _<api.githubcopilot.com>_
+  ports:
+  - number: 443
+    name: https
+    protocol: HTTPS
+  location: MESH_EXTERNAL
+  resolution: DNS
+----
++
+* Replace `_<mcp_external_server>_` with the name of your external MCP server.
+* Replace `_<mcp_test>_` with the namespace that the MCP server is in.
+* Replace `_<api.githubcopilot.com>_` with the host URL of the MCP server.
+* Replace any other values as required.
+
+. Apply the CR by running the following command:
++
+[source,terminal,subs="+quotes"]
+----
+$ oc apply -f _<mcp_external_server_se.yaml>_
+----
++
+Replace `_<mcp_external_server_se.yaml>_` with the name of your CR.

modules/proc-register-ext-mcp-server-mcpserverregistration.adoc

@@ -0,0 +1,59 @@
+// Module included in the following assemblies:
+//
+// *mcp_gateway_config/mcp-gateway-register-ext-mcp-servers.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="proc-register-ext-mcp-server-mcpserverregistration_{context}"]
+= Creating an MCPServerRegistration for an external MCP server
+
+[role="_abstract"]
+To use an external MCP server, you must create an `MCPServerRegistration` custom resource (CR) that registers your external MCP server with the MCP gateway.
+
+.Prerequisites
+
+* You completed all of the installation and configuration steps for {mcpg}.
+* You have the information for the external MCP server you want to connect to.
+* You installed the {oc-first}.
+* You are using Istio for ingress control.
+* You created `ServiceEntry`, `DestinationRule`, `HTTPRoute`, and `Secret` objects.
+* Recommended: You created an `AuthPolicy` CR.
+
+.Procedure
+
+. Create a `MCPServerRegistration` CR that registers the external MCP server with the MCP gateway by using the following example:
++
+.Example MCPServerRegistration CR
+[source,yaml,subs="+quotes"]
+----
+apiVersion: mcp.kuadrant.io/v1alpha1
+kind: MCPServerRegistration
+metadata:
+  name: _<external_mcp_server>_
+  namespace: _<mcp_test>_
+spec:
+  toolPrefix: _<"extserver_">_
+  targetRef:
+    group: "gateway.networking.k8s.io"
+    kind: "HTTPRoute"
+    name: "_<mcp_api_key_server_route>_"
+    namespace: "_<mcp_test>_"
+  credentialRef:
+    name: _<mcp_backend_secret>_
+    key: api-key
+----
++
+* Replace the `metadata.name:` field value with the name you want to use.
+* Replace the `metadata.namespace:` field value with the namespace you need to use. If you did not use a `ReferenceGrant` CR, the value of `metadata.namespace:` must be the same as the namepsace specified in the `HTTPRoute` object.
+* Replace the `spec.toolPrefix:` field with the value that you want to use to prefix the tools available with this MCP server.
+* Replace the `spec.targetRef.name:` field value with the name of the `HTTPRoute` CR you applied.
+* Replace the value of `spec.targetRef.namespace:` with the namespace where your `HTTPRoute` CR is applied.
+* The `spec.credentialRef:` field points to the `Secret` CR that has credentials for the external MCP server.
+
+. Apply the CR by running the following command:
++
+[source,terminal,subs="+quotes"]
+----
+$ oc apply -f _<mcp_external_server_mcpsr.yaml>_
+----
++
+Replace `_<mcp_external_server_mcpsr.yaml>_` with the name of your CR.

modules/proc-register-ext-mcp-server-secret.adoc

@@ -0,0 +1,56 @@
+// Module included in the following assemblies:
+//
+// *mcp_gateway_config/mcp-gateway-register-ext-mcp-servers.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="proc-register-ext-mcp-server-secret_{context}"]
+= Creating a Secret for an external MCP server
+
+[role="_abstract"]
+To use an external MCP server, you must create a `Secret` custom resource (CR) that stores backend API key credentials.
+
+This `Secret` CR is referenced in your `MCPServerRegistration` CR in the `credentialRef` parameter. These resources are for backend API key authentication. The `api-key` is stored in the config secret and used by the MCP broker component for upstream connections.
+
+.Prerequisites
+
+* You completed all of the installation and configuration steps for {mcpg}.
+* You have the information for the external MCP server you want to connect to.
+* You installed the {oc-first}.
+* You are using Istio for ingress control.
+* You created `ServiceEntry`, `DestinationRule`, and `HTTPRoute` objects.
+
+.Procedure
+
+. Create a `Secret` CR that stores backend API key credentials by using the following example:
++
+.Example Secret CR
+[source,yaml,subs="+quotes"]
+----
+apiVersion: v1
+kind: Secret
+metadata:
+  name: _<mcp_backend_auth>_
+  namespace: _<mcp_test>_
+  labels:
+    mcp.kuadrant.io/secret: "true"
+    app.kubernetes.io/part-of: mcp-gateway
+    env: production
+type: Opaque
+stringData:
+  api-key: _<"mcp_prod_12abC34...">_
+----
++
+* Replace the `metadata.name:` field value with the name you want to use. Service naming is used in this example.
+* Replace the `metadata.namespace:` field value with the namespace you used in your `ServiceEntry` object.
+* You must use the `metadata.labels.mcp.kuadrant.io/secret: "true"` field and value. If you do not use this value, the MCP gateway controller cannot see the `Secret` object.
+* The `metadata.labels.app.kubernetes.io/part-of: mcp-gateway` field and value are optional.
+* Replace your `stringData.api-key:` value with the one you need to use.
+
+. Apply the CR by running the following command:
++
+[source,terminal,subs="+quotes"]
+----
+$ oc apply -f _<mcp_external_server_secret.yaml>_
+----
++
+Replace `_<mcp_external_server_secret.yaml>_` with the name of your CR.