Merge pull request #110583 from jasonmadigan/fix/ext-mcp-server-guide-patches

Fix external MCP Gateway guides to match upstream corrections

Author: ShaunaDiaz

modules/proc-mcp-gateway-otel.adoc

@@ -34,7 +34,7 @@ The MCP gateway uses {OTELName} throughout all components to give you consistent
 .Example OpenTelemetryCollector custom resource (CR)
 [source,yaml,subs="+quotes"]
 ----
-apiVersion: opentelemetry.io/v1alpha1
+apiVersion: opentelemetry.io/v1beta1
 kind: OpenTelemetryCollector
 metadata:
   name: _<mcp_otel_collector>_
@@ -73,15 +73,16 @@ spec:
 
 . Apply the following environment variables to your {ocp} cluster by running the following command:
 +
-[source,terminal]
+[source,terminal,subs="+quotes"]
 ----
 $ oc set env deployment/mcp-gateway \
-  OTEL_EXPORTER_OTLP_ENDPOINT="http://mcp-otel-collector-collector.mcp-gateway-system.svc.cluster.local:4318" \
+  OTEL_EXPORTER_OTLP_ENDPOINT="http://_<mcp_otel_collector>_-collector._<mcp_gateway_system>_.svc.cluster.local:4318" \
   OTEL_EXPORTER_OTLP_INSECURE="true" \
   OTEL_SERVICE_NAME="mcp-gateway"
 ----
 +
-When {OTELName} creates a collector, the service name is `[metadata.name]-collector`.
+* Replace `_<mcp_otel_collector>_` with the name you used in your `OpenTelemetryCollector` CR. When {OTELName} creates a collector, the service name is `[metadata.name]-collector`.
+* Replace `_<mcp_gateway_system>_` with the namespace of your MCP gateway deployment.
 
 . Optional. If you want to send traces to one collector and logs to a different one, set the following additional environment variables:
 +

modules/proc-mcp-gateway-register-mcp-server.adoc

@@ -129,10 +129,10 @@ $ oc get mcpsr -A
 .Example output
 [source,text]
 ----
-NAMESPACE    NAME               READY   TARGET-ROUTE           PREFIX       AGE
-mcp-test     mcp-server-one     True    mcp-api-key-server     serverone    14m
-mcp-test     mcp-server-two     True    mcp-generic-route      servertwo    2d
-mcp-prod     analytics-tools    True    analytics-route        stats        5h
+NAMESPACE   NAME              PREFIX      TARGET                  PATH   READY   TOOLS   CREDENTIALS   AGE
+mcp-test    mcp-server-one    serverone   mcp-api-key-server      /mcp   True    4                     14m
+mcp-test    mcp-server-two    servertwo   mcp-generic-route       /mcp   True    7                     2d
+mcp-prod    analytics-tools   stats       analytics-route         /mcp   True    3                     5h
 ----
 
 . Check on tool discovery status by running the following command:

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

@@ -46,15 +46,12 @@ spec:
           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.
+* This `AuthPolicy` CR passes through the `Authorization` header from the original request.
 
 . Apply the CR by running the following command:
 +

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

@@ -39,7 +39,7 @@ spec:
 +
 * 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 `_<tls_mode>` with the TLS traffic policy that you need according to your requirements. `SIMPLE` is the default value. Use `MUTUAL` in high-security environments or use `ISTIO_MUTUAL` with {service-mesh}. A value of `DISABLE` means that TLS is not used.
+* The default TLS mode is `SIMPLE`. Change it to `MUTUAL` in high-security environments or use `ISTIO_MUTUAL` with {service-mesh}. A value of `DISABLE` means that TLS is not used.
 * Replace `_<api.githubcopilot.com>_` with the host URL of the MCP server.
 
 . Apply the CR by running the following command:

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

@@ -7,7 +7,7 @@
 = Verifying that your external MCP server is ready to use
 
 [role="_abstract"]
-To verify that your an external MCP server is ready to use, check the status of your `MCPServerRegistration` custom resource (CR).
+To verify that an external MCP server is ready to use, check the status of your `MCPServerRegistration` custom resource (CR).
 
 .Prerequisites
 
@@ -29,9 +29,9 @@ $ oc get mcpsr -A
 .Example output
 [source,text]
 ----
-NAMESPACE    NAME               READY   TARGET-ROUTE           PREFIX       AGE
-mcp-test     mcp-server-ext     True    external-mcp-server    extserver    14m
-mcp-test     mcp-server-one     True    mcp-api-key-server     serverone    1d
-mcp-test     mcp-server-two     True    mcp-generic-route      servertwo    2d
-mcp-prod     analytics-tools    True    analytics-route        stats        5h
+NAMESPACE   NAME              PREFIX      TARGET                  PATH   READY   TOOLS   CREDENTIALS          AGE
+mcp-test    mcp-server-ext    extserver   external-mcp-server     /mcp   True    5       ext-server-secret    14m
+mcp-test    mcp-server-one    serverone   mcp-api-key-server      /mcp   True    4                            1d
+mcp-test    mcp-server-two    servertwo   mcp-generic-route       /mcp   True    7                            2d
+mcp-prod    analytics-tools   stats       analytics-route         /mcp   True    3       analytics-secret     5h
 ----

modules/proc-verify-virt-mcp-server.adoc

@@ -14,6 +14,7 @@ After you create your virtual MCP servers, you can check that they are returning
 * You completed all of the installation and configuration steps for {mcpg}.
 * You registered your MCP servers.
 * You installed the {oc-first}.
+* You installed the `jq` command-line JSON processor.
 * You applied `MCPVirtualServer` custom resource (CRs) for your virtual servers.
 
 .Procedure
@@ -47,13 +48,13 @@ $ curl -s -D /tmp/mcp_headers -X POST _<http:example.com:port/mcp>_ \
   "result": {
     "protocolVersion": "2025-11-25",
     "capabilities": {
-      "tools": {},
-      "prompts": {},
-      "resources": {}
+      "tools": {
+        "listChanged": true
+      }
     },
     "serverInfo": {
-      "name": "mcp-gateway-server",
-      "version": "1.0.0"
+      "name": "Kuadrant MCP Gateway",
+      "version": "0.0.1"
     }
   }
 }
@@ -66,10 +67,11 @@ $ curl -s -D /tmp/mcp_headers -X POST _<http:example.com:port/mcp>_ \
 $ SESSION_ID=$(grep -i "mcp-session-id:" /tmp/mcp_headers | cut -d' ' -f2 | tr -d '\r')
 ----
 +
-.Expected output
-[source,text]
+Verify that the session ID was extracted by running the following command:
++
+[source,terminal]
 ----
-echo "MCP Session ID: $SESSION_ID"
+$ echo "MCP Session ID: $SESSION_ID"
 ----
 
 . Request the tools from the `dev_tools` virtual MCP server by running the following command:
@@ -92,7 +94,7 @@ $ curl -X POST _<http:example.com:port/mcp>_ \
 +
 [source,terminal,subs="+quotes"]
 ----
-$ curl -X POST _<http:example.com:port>_/mcp \
+$ curl -X POST _<http:example.com:port/mcp>_ \
   -H "Content-Type: application/json" \
   -H "mcp-session-id: $SESSION_ID" \
   -H "X-Mcp-Virtualserver: _<mcp_system>_/_<data_tools>_" \
@@ -108,7 +110,7 @@ $ curl -X POST _<http:example.com:port>_/mcp \
 +
 [source,terminal,subs="+quotes"]
 ----
-$ curl -X POST _<http:example.com:port>_/mcp \
+$ curl -X POST _<http:example.com:port/mcp>_ \
   -H "mcp-session-id: $SESSION_ID" \
   -H "Content-Type: application/json" \
   -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | jq '.result.tools[].name'