Skip to content

Commit cab138f

Browse files
ShaunaDiazShaunaDiaz
authored
Merge pull request #109575 from ShaunaDiaz/OSDOCS-18939
OSDOCS-18939: adds external MCP server registration to gateway docs
2 parents c0723ee + 9e204a6 commit cab138f

10 files changed

Lines changed: 420 additions & 1 deletion

‎_attributes/attributes.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020
:ocp-min-version: 4.19
2121
:oc-first: pass:quotes[OpenShift CLI (`oc`)]
2222

23-
:service-mesh: OpenShift Service Mesh
23+
:ossm: OpenShift Service Mesh
2424
:service-mesh-version: 3.2
2525

2626
:cert-manager: cert-manager Operator for Red Hat OpenShift

‎_topic_maps/_topic_map.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,8 @@ Distros: rhcl
7575
Topics:
7676
- Name: Registering on-premise MCP servers
7777
File: mcp-gateway-register-on-prem-mcp-servers
78+
- Name: Registering external MCP servers
79+
File: mcp-gateway-register-ext-mcp-servers
7880
- Name: Configuring authentication for the MCP gateway
7981
File: mcp-gateway-authz
8082
- Name: Configuring authorization for the MCP gateway

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

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="mcp-gateway-register-ext-mcp-servers"]
3+
= Registering external MCP servers
4+
include::_attributes/attributes.adoc[]
5+
:context: mcp-gateway-register-ext-mcp-servers
6+
7+
[role="_abstract"]
8+
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.
9+
10+
include::modules/proc-register-ext-mcp-server-ingress.adoc[leveloffset=+1]
11+
12+
include::modules/proc-register-ext-mcp-server-tls.adoc[leveloffset=+1]
13+
14+
include::modules/proc-register-ext-mcp-server-httproute.adoc[leveloffset=+1]
15+
16+
include::modules/proc-register-ext-mcp-server-secret.adoc[leveloffset=+1]
17+
18+
include::modules/proc-register-ext-mcp-server-authpolicy.adoc[leveloffset=+1]
19+
20+
include::modules/proc-register-ext-mcp-server-mcpserverregistration.adoc[leveloffset=+1]
21+
22+
include::modules/proc-register-ext-mcp-server-verify.adoc[leveloffset=+1]

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

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
// Module included in the following assemblies:
2+
//
3+
// *mcp_gateway_config/mcp-gateway-register-ext-mcp-servers.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="proc-register-ext-mcp-server-authpolicy_{context}"]
7+
= Creating an AuthPolicy for an external MCP server
8+
9+
[role="_abstract"]
10+
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.
11+
12+
[NOTE]
13+
====
14+
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.
15+
====
16+
17+
.Prerequisites
18+
19+
* You completed all of the installation and configuration steps for {mcpg}.
20+
* You have the information for the external MCP server you want to connect to.
21+
* You installed the {oc-first}.
22+
* You are using Istio for ingress control.
23+
* You created `ServiceEntry`, `DestinationRule`, and `HTTPRoute` objects.
24+
25+
.Procedure
26+
27+
. Create an `AuthPolicy` CR that handles authorization headers by using the following example:
28+
+
29+
.Example AuthPolicy CR
30+
[source,yaml,subs="+quotes"]
31+
----
32+
apiVersion: kuadrant.io/v1
33+
kind: AuthPolicy
34+
metadata:
35+
name: _<mcps_auth_policy>_
36+
namespace: _<mcp_test>_
37+
spec:
38+
targetRef:
39+
group: gateway.networking.k8s.io
40+
kind: HTTPRoute
41+
name: _<mcp_external_server>_
42+
rules:
43+
response:
44+
success:
45+
headers:
46+
authorization:
47+
plain:
48+
expression: 'request.headers["authorization"]'
49+
x-mcp-api-key:
50+
plain:
51+
expression: 'request.headers["authorization"].split(" ")[1]'
52+
----
53+
+
54+
* Replace the `metadata.name:` field value with the name you want to use. This approach uses service naming.
55+
* Replace the `metadata.namespace:` field value with the namespace you used in your `ServiceEntry` object.
56+
* Replace the `spec.name:` value with the name of your external MCP server route.
57+
* This `AuthPolicy` CR extracts the API key from the OAuth token and sets it as the `x-mcp-api-key` header.
58+
59+
. Apply the CR by running the following command:
60+
+
61+
[source,terminal,subs="+quotes"]
62+
----
63+
$ oc apply -f _<mcp_external_server_authpolicy.yaml>_
64+
----
65+
+
66+
Replace `_<mcp_external_server_authpolicy.yaml>_` with the name of your CR.

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

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
// Module included in the following assemblies:
2+
//
3+
// *mcp_gateway_config/mcp-gateway-register-ext-mcp-servers.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="proc-register-ext-mcp-server-httproute_{context}"]
7+
= Creating an HTTPRoute for an external MCP server
8+
9+
[role="_abstract"]
10+
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.
11+
12+
.Prerequisites
13+
14+
* You completed all of the installation and configuration steps for {mcpg}.
15+
* You have the information for the external MCP server you want to connect to.
16+
* You installed the {oc-first}.
17+
* You are using Istio for ingress control.
18+
* You created `ServiceEntry` and `DestinationRule` objects.
19+
20+
.Procedure
21+
22+
. Create a `HTTPRoute` CR that routes to the external service by using the following example:
23+
+
24+
.Example HTTPRoute CR
25+
[source,yaml,subs="+quotes"]
26+
----
27+
apiVersion: gateway.networking.k8s.io/v1
28+
kind: HTTPRoute
29+
metadata:
30+
name: _<mcp_external_server>_
31+
namespace: _<mcp_test>_
32+
spec:
33+
parentRefs:
34+
- group: gateway.networking.k8s.io
35+
kind: Gateway
36+
name: _<mcp_gateway>_
37+
namespace: _<gateway_system>_
38+
hostnames:
39+
- example.mcp.local
40+
rules:
41+
- matches:
42+
- path:
43+
type: PathPrefix
44+
value: /mcp
45+
filters:
46+
- type: URLRewrite
47+
urlRewrite:
48+
hostname: _<api.externalhostname.com>_
49+
backendRefs:
50+
- name: _<api.example.com>_
51+
kind: Hostname
52+
group: networking.istio.io
53+
port: 443
54+
----
55+
+
56+
* Replace the `metadata.name:` field value with the name of your external MCP server.
57+
* Replace the `metadata.namespace:` field value with the namespace that the MCP server is in.
58+
* Set the `spec.parentRefs:` fields to match your MCP `Gateway` object.
59+
* The `spec.hostnames:` field value is your internal hostname. It must match your `*.mcp.local` `Gateway` CR value.
60+
* The `spec.rules.matches.path.value:` field value is your MCP gateway endpoint. In this example, `/mcp` is used.
61+
* Replace the value of `spec.rules.filters.urlRewrite.hostname:` with your external hostname.
62+
* Replace the `spec.rules.backendRefs.name:` field value with the host URL of the MCP server.
63+
64+
. Apply the CR by running the following command:
65+
+
66+
[source,terminal,subs="+quotes"]
67+
----
68+
$ oc apply -f _<mcp_external_server_httproute.yaml>_
69+
----
70+
+
71+
Replace `_<mcp_external_server_httproute.yaml>_` with the name of your CR.

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

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
// Module included in the following assemblies:
2+
//
3+
// *mcp_gateway_config/mcp-gateway-register-ext-mcp-servers.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="proc-register-ext-mcp-server-serviceentry_{context}"]
7+
= Creating a ServiceEntry for an external MCP server
8+
9+
[role="_abstract"]
10+
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.
11+
12+
.Prerequisites
13+
14+
* You completed all of the installation and configuration steps for {mcpg}.
15+
* You have the information for the external MCP server you want to connect to.
16+
* You installed the {oc-first}.
17+
* You are using Istio for ingress control.
18+
19+
.Procedure
20+
21+
. Create a `ServiceEntry` CR that registers the external server in the Istio service registry by using the following template:
22+
+
23+
.Example ServiceEntry CR
24+
[source,yaml,subs="+quotes"]
25+
----
26+
apiVersion: networking.istio.io/v1beta1
27+
kind: ServiceEntry
28+
metadata:
29+
name: _<mcp_external_server>_
30+
namespace: _<mcp_test>_
31+
spec:
32+
hosts:
33+
- _<api.githubcopilot.com>_
34+
ports:
35+
- number: 443
36+
name: https
37+
protocol: HTTPS
38+
location: MESH_EXTERNAL
39+
resolution: DNS
40+
----
41+
+
42+
* Replace `_<mcp_external_server>_` with the name of your external MCP server.
43+
* Replace `_<mcp_test>_` with the namespace that the MCP server is in.
44+
* Replace `_<api.githubcopilot.com>_` with the host URL of the MCP server.
45+
* Replace any other values as required.
46+
47+
. Apply the CR by running the following command:
48+
+
49+
[source,terminal,subs="+quotes"]
50+
----
51+
$ oc apply -f _<mcp_external_server_se.yaml>_
52+
----
53+
+
54+
Replace `_<mcp_external_server_se.yaml>_` with the name of your CR.

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

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
// Module included in the following assemblies:
2+
//
3+
// *mcp_gateway_config/mcp-gateway-register-ext-mcp-servers.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="proc-register-ext-mcp-server-mcpserverregistration_{context}"]
7+
= Creating an MCPServerRegistration for an external MCP server
8+
9+
[role="_abstract"]
10+
To use an external MCP server, you must create an `MCPServerRegistration` custom resource (CR) that registers your external MCP server with the MCP gateway.
11+
12+
.Prerequisites
13+
14+
* You completed all of the installation and configuration steps for {mcpg}.
15+
* You have the information for the external MCP server you want to connect to.
16+
* You installed the {oc-first}.
17+
* You are using Istio for ingress control.
18+
* You created `ServiceEntry`, `DestinationRule`, `HTTPRoute`, and `Secret` objects.
19+
* Recommended: You created an `AuthPolicy` CR.
20+
21+
.Procedure
22+
23+
. Create a `MCPServerRegistration` CR that registers the external MCP server with the MCP gateway by using the following example:
24+
+
25+
.Example MCPServerRegistration CR
26+
[source,yaml,subs="+quotes"]
27+
----
28+
apiVersion: mcp.kuadrant.io/v1alpha1
29+
kind: MCPServerRegistration
30+
metadata:
31+
name: _<external_mcp_server>_
32+
namespace: _<mcp_test>_
33+
spec:
34+
toolPrefix: _<"extserver_">_
35+
targetRef:
36+
group: "gateway.networking.k8s.io"
37+
kind: "HTTPRoute"
38+
name: "_<mcp_api_key_server_route>_"
39+
namespace: "_<mcp_test>_"
40+
credentialRef:
41+
name: _<mcp_backend_secret>_
42+
key: api-key
43+
----
44+
+
45+
* Replace the `metadata.name:` field value with the name you want to use.
46+
* 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.
47+
* Replace the `spec.toolPrefix:` field with the value that you want to use to prefix the tools available with this MCP server.
48+
* Replace the `spec.targetRef.name:` field value with the name of the `HTTPRoute` CR you applied.
49+
* Replace the value of `spec.targetRef.namespace:` with the namespace where your `HTTPRoute` CR is applied.
50+
* The `spec.credentialRef:` field points to the `Secret` CR that has credentials for the external MCP server.
51+
52+
. Apply the CR by running the following command:
53+
+
54+
[source,terminal,subs="+quotes"]
55+
----
56+
$ oc apply -f _<mcp_external_server_mcpsr.yaml>_
57+
----
58+
+
59+
Replace `_<mcp_external_server_mcpsr.yaml>_` with the name of your CR.

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

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
// Module included in the following assemblies:
2+
//
3+
// *mcp_gateway_config/mcp-gateway-register-ext-mcp-servers.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="proc-register-ext-mcp-server-secret_{context}"]
7+
= Creating a Secret for an external MCP server
8+
9+
[role="_abstract"]
10+
To use an external MCP server, you must create a `Secret` custom resource (CR) that stores backend API key credentials.
11+
12+
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.
13+
14+
.Prerequisites
15+
16+
* You completed all of the installation and configuration steps for {mcpg}.
17+
* You have the information for the external MCP server you want to connect to.
18+
* You installed the {oc-first}.
19+
* You are using Istio for ingress control.
20+
* You created `ServiceEntry`, `DestinationRule`, and `HTTPRoute` objects.
21+
22+
.Procedure
23+
24+
. Create a `Secret` CR that stores backend API key credentials by using the following example:
25+
+
26+
.Example Secret CR
27+
[source,yaml,subs="+quotes"]
28+
----
29+
apiVersion: v1
30+
kind: Secret
31+
metadata:
32+
name: _<mcp_backend_auth>_
33+
namespace: _<mcp_test>_
34+
labels:
35+
mcp.kuadrant.io/secret: "true"
36+
app.kubernetes.io/part-of: mcp-gateway
37+
env: production
38+
type: Opaque
39+
stringData:
40+
api-key: _<"mcp_prod_12abC34...">_
41+
----
42+
+
43+
* Replace the `metadata.name:` field value with the name you want to use. Service naming is used in this example.
44+
* Replace the `metadata.namespace:` field value with the namespace you used in your `ServiceEntry` object.
45+
* 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.
46+
* The `metadata.labels.app.kubernetes.io/part-of: mcp-gateway` field and value are optional.
47+
* Replace your `stringData.api-key:` value with the one you need to use.
48+
49+
. Apply the CR by running the following command:
50+
+
51+
[source,terminal,subs="+quotes"]
52+
----
53+
$ oc apply -f _<mcp_external_server_secret.yaml>_
54+
----
55+
+
56+
Replace `_<mcp_external_server_secret.yaml>_` with the name of your CR.

0 commit comments

Comments
 (0)