Skip to content

Commit 5a3fa40

Browse files
ShaunaDiazShaunaDiaz
committed
OSDOCS-18936: adds listener and route config MCP gateway
1 parent 6bd0d6d commit 5a3fa40

7 files changed

Lines changed: 330 additions & 20 deletions

‎_topic_maps/_topic_map.yml‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -73,10 +73,8 @@ Name: Configuring the MCP gateway, register servers, and create policies
7373
Dir: mcp_gateway_config
7474
Distros: rhcl
7575
Topics:
76-
- Name: Configuring the MCP gateway
77-
File: mcp-gateway-config-listener-route
78-
- Name: Register MCP servers
79-
File: mcp-gateway-register-servers
76+
- Name: Registering on-premise MCP servers
77+
File: mcp-gateway-register-on-prem-mcp-servers
8078
- Name: Configuring authentication for the MCP gateway
8179
File: mcp-gateway-authz
8280
- Name: Configuring authorization for the MCP gateway

‎mcp_gateway_config/mcp-gateway-config-listener-route.adoc‎

Lines changed: 0 additions & 8 deletions
This file was deleted.

‎mcp_gateway_config/mcp-gateway-register-on-prem-mcp-servers.adoc‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="mcp-gateway-register-on-prem-mcp-servers"]
3+
= Registering on-prem MCP servers
4+
include::_attributes/attributes.adoc[]
5+
:context: mcp-gateway-register-servers
6+
7+
[role="_abstract"]
8+
To begin using MCP servers with your {mcpg}, you must register each server by creating an `HTTPRoute` custom resource (CR) and a corresponding `MCPServerRegistration` CR that references the route.
9+
10+
include::modules/proc-mcp-gateway-register-mcp-server.adoc[leveloffset=+1]
11+
12+
include::modules/ref-mcp-gateway-mcpserverregistration-cr.adoc[leveloffset=+2]
13+
14+
include::modules/proc-mcp-gateway-verify-mcp-server-registration.adoc[leveloffset=+1]

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

Lines changed: 0 additions & 8 deletions
This file was deleted.

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

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
// Module included in the following assemblies:
2+
//
3+
// *mcp_gateway_config/mcp-gateway-register-servers.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="proc-register-mcp-server_{context}"]
7+
= Registering an MCP server for use with the MCP gateway
8+
9+
[role="_abstract"]
10+
Direct your {mcpg} to discover and route to your MCP servers by registering them. To connect each MCP server to the {mcpg}, you must first create an `HTTPRoute` custom resource (CR) that routes to the server. Then, you must create an `MCPServerRegistration` custom resource (CR) that references the `HTTPRoute` CR.
11+
12+
.Prerequisites
13+
14+
* You installed the {mcpg}.
15+
* You have a `Gateway` object configured with your requirements.
16+
* You configured a listener for the {mcpg}.
17+
* You created an `HTTPRoute` CR for the {mcpg}.
18+
* You created and applied an `MCPGatewayExtension` CR.
19+
* If you are using a gateway in a namespace that is different from the one where the `MCPGatewayExtension` CR was applied, you created a `ReferenceGrant` object.
20+
* You are logged into an {ocp} cluster with an `admin` role.
21+
22+
.Procedure
23+
24+
. Create an `HTTPRoute` CR that routes to your MCP server by using the following template:
25+
+
26+
.Example HTTPRoute CR
27+
[source,yaml,subs="+quotes"]
28+
----
29+
apiVersion: gateway.networking.k8s.io/v1
30+
kind: HTTPRoute
31+
metadata:
32+
name: _<mcp_api_key_server_route>_
33+
namespace: _<mcp_test>_
34+
labels:
35+
mcp-server: 'true'
36+
spec:
37+
parentRefs:
38+
- name: _<mcp_gateway>_
39+
namespace: _<gateway_system>_
40+
hostnames:
41+
- 'api-key-server.mcp.local'
42+
rules:
43+
- matches:
44+
- path:
45+
type: PathPrefix
46+
value: /
47+
backendRefs:
48+
- name: _<mcp_api_key_server>_
49+
port: 9090
50+
----
51+
+
52+
* For the `metadata.name:` parameter value, replace `_<mcp_api_key_server_route>_` with the name of the http route.
53+
* For the `metadata.namespace:` parameter value, replace `_<mcp_test>_` with the namespace you need to use. The `HTTPRoute` CR must be in the same namespace as the `MCPServerRegistration` CR unless `targetRef.namespace` is set in the `MCPServerRegistration` CR.
54+
* For the `spec.parentRefs.name:` and `spec.parentRefs.namespace:` parameter values, use the values from the `Gateway` CR that you are targeting.
55+
* For the `spec.hostnames:` parameter value, replace the list with your required internal routing hostname.
56+
* For the `spec.rules.backendRefs.name:` parameter value, replace `_<mcp_api_key_server>_` with your {mcpg} service name.
57+
* For the `spec.rules.backendRefs.port:` parameter value, replace `9090` with your MCP server port.
58+
59+
. Apply the CR by running the following command:
60+
+
61+
[source,terminal,subs="+quotes"]
62+
----
63+
$ oc apply -f _<mcp_api_key_server_route>_
64+
----
65+
+
66+
Replace `_<mcp_api_key_server_route>_` with the name of the http route you created.
67+
68+
. Create an `MCPServerRegistration` CR that references your `HTTPRoute` CR by using the following template:
69+
+
70+
.Example MCPServerRegistration CR
71+
[source,yaml,subs="+quotes"]
72+
----
73+
apiVersion: mcp.kuadrant.io/v1alpha1
74+
kind: MCPServerRegistration
75+
metadata:
76+
name: _<mcp_server_one>_
77+
namespace: _<mcp_test>_
78+
spec:
79+
toolPrefix: _<serverone_>_
80+
targetRef:
81+
group: "gateway.networking.k8s.io"
82+
kind: "HTTPRoute"
83+
name: "_<mcp_api_key_server_route>_"
84+
namespace: "_<mcp_test>_"
85+
credentialRef:
86+
name: _<mcp_server_one_secret>_
87+
key: api-key
88+
----
89+
+
90+
* Replace the `metadata.name:` and `metadata.namespace:` field values with the ones you want to use. If you did not use a `ReferenceGrant` CR, the value of `metadata.namespace:` must be the same as specified in the `HTTPRoute` object.
91+
* Replace the `spec.toolPrefix:` field with the value that you want to prefix the tools available with this MCP server.
92+
* Replace the `spec.targetRef.name field` value with the name of the `HTTPRoute` CR you applied. In this example, `_<mcp_api_key_server_route>_` is used.
93+
* Replace the `spec.targetRef.namespace:` field value with the namespace where your `HTTPRoute` CR is applied. In this example, `_<mcp_test>_` is used.
94+
* Replace the `credentialRef.name:` field value with the name of your `Secret` CR. In this example, `_<mcp_server_one_secret>_` is used. You can omit this parameter if your MCP server does not require authentication or authorization.
95+
* For more information about these parameters, see "Understanding the `MCPServerRegistration` custom resource."
96+
97+
. Apply the CR by running the following command:
98+
+
99+
[source,terminal,subs="+quotes"]
100+
----
101+
$ oc apply -f _<mcp_server_one>_
102+
----
103+
+
104+
Replace `_<mcp_server_one>_` with the `name` of your `MCPServerRegistration` CR.
105+
106+
. Check the status of your current `MCPServerRegistration` CR by running the following command:
107+
+
108+
[source,terminal,subs="+quotes"]
109+
----
110+
$ oc get mcpsr -n _<mcp_server_one>_
111+
----
112+
+
113+
Replace `_<mcp_server_one>_` with the `name` of your `MCPServerRegistration` CR.
114+
+
115+
.Example output
116+
[source,text]
117+
----
118+
NAMESPACE NAME PREFIX TARGET PATH READY TOOLS CREDENTIALS AGE
119+
mcp-test my-mcp-server myserver_ mcp-api-key-server-route /mcp True 4 30s
120+
----
121+
122+
. Check the status of all `MCPServerRegistration` CRs in the cluster by running the following command:
123+
+
124+
[source,terminal]
125+
----
126+
$ oc get mcpsr -A
127+
----
128+
+
129+
.Example output
130+
[source,text]
131+
----
132+
NAMESPACE NAME READY TARGET-ROUTE PREFIX AGE
133+
mcp-test mcp-server-one True mcp-api-key-server serverone 14m
134+
mcp-test mcp-server-two True mcp-generic-route servertwo 2d
135+
mcp-prod analytics-tools True analytics-route stats 5h
136+
----
137+
138+
. Check on tool discovery status by running the following command:
139+
+
140+
[source,terminal]
141+
----
142+
$ oc get mcpsr -A -o yaml
143+
----
144+
+
145+
.Example output
146+
[source,yaml]
147+
----
148+
apiVersion: v1
149+
items:
150+
- apiVersion: mcp.kuadrant.io/v1alpha1
151+
kind: MCPServerRegistration
152+
metadata:
153+
annotations:
154+
kubectl.kubernetes.io/last-applied-configuration: |
155+
{"apiVersion":"mcp.kuadrant.io/v1alpha1","kind":"MCPServerRegistration","metadata":{"annotations":{},"labels":{"mcp.kuadrant.io/managed":"true"},"name":"test-server1","namespace":"mcp-test"},"spec":{"targetRef":{"group":"gateway.networking.k8s.io","kind":"HTTPRoute","name":"mcp-server1-route"},"toolPrefix":"test1_"}}
156+
creationTimestamp: "2026-03-31T09:50:26Z"
157+
finalizers:
158+
- mcp.kuadrant.io/finalizer
159+
generation: 1
160+
labels:
161+
mcp.kuadrant.io/managed: "true"
162+
name: test-server1
163+
namespace: mcp-test
164+
resourceVersion: "302234"
165+
uid: d9603011-2e0f-4f3f-88d6-eda986f365d1
166+
spec:
167+
path: /mcp
168+
targetRef:
169+
group: gateway.networking.k8s.io
170+
kind: HTTPRoute
171+
name: mcp-server1-route
172+
toolPrefix: test1_
173+
status:
174+
conditions:
175+
- lastTransitionTime: "2026-04-07T08:49:53Z"
176+
message: server added successfully. Total tools added 5
177+
reason: Ready
178+
status: "True"
179+
type: Ready
180+
discoveredTools: 5
181+
kind: List
182+
metadata:
183+
resourceVersion: "
184+
----
185+
+
186+
When you examine the `status` block for `discoveredTools`, you can see that the `status.conditions:` fields show that an MCP server is present and that tools are available and ready.

‎modules/proc-mcp-gateway-verify-mcp-server-registration.adoc‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
2+
// Module included in the following assemblies:
3+
//
4+
// *mcp_gateway_config/mcp-gateway-register-servers.adoc
5+
6+
:_mod-docs-content-type: PROCEDURE
7+
[id="proc-mcp-gateway-verify-mcp-server-registration_{context}"]
8+
= Verifying an MCP server registration
9+
10+
[role="_abstract"]
11+
You can test that your MCP server tools are available through the MCP gateway by starting a session and listing available tools.
12+
13+
.Prerequisites
14+
15+
* You registered the MCP server you want to verify.
16+
* You completed all {mcpg} installation and configuration steps.
17+
18+
.Procedure
19+
20+
. Connect to the MCP gateway and initialize a session to dump response headers to a file by running the following command:
21+
+
22+
[source,terminal]
23+
----
24+
$ curl -s -D /tmp/mcp_headers -X POST http://_<example.com>_/mcp \
25+
-H "Content-Type: application/json" \
26+
-d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-11-25", "capabilities": {}, "clientInfo": {"name": "test-client", "version": "1.0.0"}}}'
27+
----
28+
+
29+
Replace _<example.com>_ with your URL and port.
30+
31+
. Extract the MCP session ID from the dumped response headers by running the following command:
32+
+
33+
[source,terminal]
34+
----
35+
$ SESSION_ID=$(grep -i "mcp-session-id:" /tmp/mcp_headers | cut -d' ' -f2 | tr -d '\r') \
36+
echo "MCP Session ID: $SESSION_ID"
37+
----
38+
39+
. List the tools using the session ID by running the following command:
40+
+
41+
[source,terminal,subs="+quotes"]
42+
----
43+
$ curl -X POST http://_<example.com>_/mcp \
44+
-H "Content-Type: application/json" \
45+
-H "mcp-session-id: $SESSION_ID" \
46+
-d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'
47+
----
48+
+
49+
Replace _<example.com>_ with your URL and port.
50+
Your MCP server tools are listed in the response, prefixed with the `toolPrefix` value you configured in the `MCPServerRegistration` CR.
51+
52+
. Clean up by running the following command:
53+
+
54+
[source,terminal]
55+
----
56+
$ rm -f /tmp/mcp_headers
57+
----

‎modules/ref-mcp-gateway-mcpserverregistration-cr.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-servers.adoc
4+
5+
:_mod-docs-content-type: REFERENCE
6+
[id="ref-mcp-server-registration-cr_{context}"]
7+
= Understanding the MCPServerRegistration custom resource
8+
9+
[role="_abstract"]
10+
You can explore the required parts and values for an `MCPServerRegistration` custom resource (CR) by studying the references contained here.
11+
12+
.MCPServerRegistration
13+
14+
[width="100%",cols="23%,19%,^26%,32%",options="header",]
15+
|===
16+
|*Field* |*Type* |*Required* |*Description*
17+
|`spec` |MCPServerRegistrationSpec |Yes
18+
|The specification for the `MCPServerRegistration` CR
19+
20+
|`status`
21+
|MCPServerRegistrationStatus |No |The status for the CR
22+
|===
23+
24+
.MCPServerRegistrationSpec
25+
26+
[width="100%",cols="23%,19%,^26%,32%",options="header",]
27+
|===
28+
|*Field* |*Type* |*Required* |*Description*
29+
|`targetRef` |TargetReference |Yes |An `HTTPRoute` object that points to a backend MCP server. The controller discovers the backend service from this `HTTPRoute` CR and configures the broker to consolidate the MCP server's tools.
30+
31+
|`toolPrefix` |String |No |The prefix added to all consolidated tools from referenced servers. Avoids naming conflicts when aggregating tools from multiple sources, such as `server1++_++search` and `server2++_++search`. Immutable setting.
32+
33+
|`path` |String |No |The URL path where the MCP server endpoint is exposed. Default value is `/mcp`.
34+
35+
|`credentialRef` |SecretReference |No |Reference to a `Secret` object that contains authentication credentials. The secret must have the `mcp.kuadrant.io/secret=true` label. The gateway makes the credentials available to the broker automatically.
36+
|===
37+
38+
.TargetReference
39+
40+
[width="100%",cols="23%,19%,^26%,32%",options="header",]
41+
|===
42+
|*Field* |*Type* |*Required* |*Description*
43+
|`group` |String |No |Group of the target resource. Default value is `gateway.networking.k8s.io`.
44+
45+
|`kind` |String |No |Kind of the target resource. Default value is `HTTPRoute`.
46+
47+
|`name` |String |Yes |Name of the target `HTTPRoute` object.
48+
49+
|`namespace` |String |No |Namespace of the target resource. Defaults to same namespace.
50+
|===
51+
52+
.SecretReference
53+
54+
[width="100%",cols="23%,19%,^26%,32%",options="header",]
55+
|===
56+
|*Field* |*Type* |*Required* |*Description*
57+
|`name` |String |Yes |Name of the `Secret` CR.
58+
59+
|`key` |String |No |Key within the `Secret` CR that has the credential value. Default value is `token`.
60+
|===
61+
62+
.MCPServerRegistrationStatus
63+
64+
[width="100%",cols="30%,26%,44%",options="header",]
65+
|===
66+
|*Field* |*Type* |*Description*
67+
|`conditions` |link:https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1++#++Condition[++Kubernetes meta/v1.Condition++]
68+
|List of conditions that define the status of the Kubernetes resource.
69+
70+
|`discoveredTools` |Integer |Number of tools discovered from this `MCPServerRegistration` CR.
71+
|===

0 commit comments

Comments
 (0)