Skip to content

Commit 80ad2f8

Browse files
ShaunaDiazShaunaDiaz
authored
Merge pull request #109364 from ShaunaDiaz/OSDOCS-17693
OSDOCS-17693: adds install to MCP gateway docs
2 parents c384fd7 + f796ad5 commit 80ad2f8

13 files changed

Lines changed: 783 additions & 12 deletions

‎_topic_maps/_topic_map.yml‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -55,8 +55,6 @@ Name: Installing the MCP gateway
5555
Dir: mcp_gateway_install
5656
Distros: rhcl
5757
Topics:
58-
- Name: Getting started with the MCP gateway
59-
File: mcp-gateway-get-started
6058
- Name: Installing MCP gateway
6159
File: mcp-gateway-install
6260
---

‎mcp_gateway_install/mcp-gateway-get-started.adoc‎

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

‎mcp_gateway_install/mcp-gateway-install.adoc‎

Lines changed: 26 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,32 @@
11
:_mod-docs-content-type: ASSEMBLY
22
include::_attributes/attributes.adoc[]
33
[id="mcp-gateway-install"]
4-
= Installing {mcpg}
4+
= Installing and configuring {mcpg}
55
:context: mcp-gateway-get-install
66

77
[role="_abstract"]
8-
FPO assembly
8+
You can get started with the MCP gateway by installing the Operator by using Operator Lifecycle Manager (OLM), and then continuing to set up connections by applying the custom resources that you require.
9+
10+
:FeatureName: {mcpg}
11+
12+
include::snippets/technology-preview.adoc[leveloffset=+1]
13+
14+
include::modules/proc-mcp-gateway-install-olm.adoc[leveloffset=+1]
15+
16+
include::modules/proc-config-mcp-gateway-gateway.adoc[leveloffset=+1]
17+
18+
include::modules/proc-config-mcp-gateway-listener.adoc[leveloffset=+1]
19+
20+
include::modules/con-mcp-gateway-install-olm-ext-cr.adoc[leveloffset=+1]
21+
22+
include::modules/ref-mcp-gateway-auto-route.adoc[leveloffset=+2]
23+
24+
include::modules/proc-mcp-gateway-referencegrant.adoc[leveloffset=+1]
25+
26+
include::modules/proc-mcp-gateway-install-olm-ext-cr.adoc[leveloffset=+1]
27+
28+
include::modules/con-mcp-gateway-dns-management.adoc[leveloffset=+1]
29+
30+
include::modules/proc-mcp-gateway-custom-route.adoc[leveloffset=+1]
31+
32+
include::modules/proc-mcp-gateway-config-verify.adoc[leveloffset=+1]

‎modules/con-mcp-gateway-dns-management.adoc‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
// Module included in the following assemblies:
2+
//
3+
// *mcp_gateway_install/mcp-gateway-install.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="con-dns-management-mcp-gateway_{context}"]
7+
= DNS management with the MCP gateway
8+
9+
[role="_abstract"]
10+
You can use a variety of options to enable the resolution of `hostnames` associated within your `Gateway` object listeners, depending on the operating environment and targeted hostname.
11+
12+
For example, if the `hostname` is within the DNS zone defined by a `dns.config.openshift.io/cluster` resource, you can use the OpenShift Cluster Ingress Operator to register the IP address of the `Gateway` object in the associated cloud DNS provider. You must create the `Gateway` object in the namespace where the `IngressController` object is applied.
13+
14+
In environments where {ocp} is not connected to a cloud provider, you must take additional steps to manage how the `Gateway` object is exposed outside the cluster and how traffic is resolved. You can use MetalLB to advertise IP addresses associated with the `Gateway` object. You can then either perform DNS registration manually, or use automation, such as the ExternalDNS Operator.
15+
16+
When `Gateway` and `MCPGatewayExtension` objects are applied in different namespaces, such as `openshift-ingress` and `mcp-system`, you must create a `ReferenceGrant` custom resource for cross-namespace communication.

‎modules/con-mcp-gateway-install-olm-ext-cr.adoc‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
// Module included in the following assemblies:
2+
//
3+
// *mcp_gateway_install/mcp-gateway-install.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="con-mcp-gateway-install-olm-ext-cr_{context}"]
7+
= Understanding the MCPGatewayExtension custom resource
8+
9+
[role="_abstract"]
10+
You can deploy multiple MCP gateway instances within a single cluster by using more than one `Gateway` object, and an `MCPGatewayExtension` custom resource (CR) for each defined gateway. Each deployment of the MCP gateway manages its associated MCP servers by using the `MCPGatewayExtension` controller in the following ways:
11+
12+
* Defines which `Gateway` object the MCP gateway instance is responsible for.
13+
* Determines where configuration `Secret` objects are created.
14+
* Enables isolation by allowing multiple MCP gateway instances in different namespaces to target different `Gateway` objects.
15+
16+
[IMPORTANT]
17+
====
18+
Each namespace can only have one `MCPGatewayExtension` CR.
19+
Each `Gateway` object can have only one `MCPGatewayExtension` CR. If more than one `MCPGatewayExtension` CR targets the same `Gateway` object, the controller marks newer ones as conflicted. The oldest `MCPGatewayExtension` CR wins.
20+
====
21+
22+
Automatic route creation::
23+
24+
The `MCPGatewayExtension` controller automatically creates an `HTTPRoute` CR named `mcp-gateway-route`. The automatically created `HTTPRoute` CR has the following characteristics:
25+
26+
* Routes `/mcp` traffic to the `mcp-gateway` broker service on port `8080`
27+
* Uses the `hostname` from the `Gateway` listener. Wildcards such as `*.example.com` become `mcp.example.com`
28+
* References the target gateway with the correct `sectionName`
29+
* Is owned by the `MCPGatewayExtension` controller and is cleaned up automatically if the controller is deleted
30+
31+
Custom route creation::
32+
33+
If you require custom route, you can disable automatic `HTTPRoute` CR creation by setting the `spec.httpRouteManagement:` parameter to `Disabled` in your `MCPGatewayExtension` CR. After you create the `MCPGatewayExtension` CR, you can create a custom `HTTPRoute` CR.

‎modules/proc-config-mcp-gateway-gateway.adoc‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
// Module included in the following assemblies:
2+
//
3+
// *mcp_gateway_install/mcp-gateway-install.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="proc-config-mcp-gateway-gateway_{context}"]
7+
= Creating a Gateway object for your MCP gateway
8+
9+
[role="_abstract"]
10+
You must create a `Gateway` object and configure listeners to create pods to handle your traffic, assign IP addresses, and give HTTP routes a place to connect.
11+
12+
[TIP]
13+
====
14+
You can attach your {prodnamefull} `DNSPolicy` CR to your `Gateway` object to automatically map your hostnames to your Gateway object's IP address. Point your `DNSPolicy` CR to your Gateway object by `name` in the `targetRef:` section. The `DNSPolicy` CR must reside in the same namespace as the `Gateway` object.
15+
====
16+
17+
.Prerequisites
18+
19+
* You installed {ocp}.
20+
* You installed {oc-first}.
21+
* You installed the {mcpg} Operator.
22+
23+
.Procedure
24+
25+
* Create a `Gateway` object by using the following example as a template:
26+
+
27+
.Example Gateway CR with listeners
28+
[source,yaml]
29+
----
30+
apiVersion: gateway.networking.k8s.io/v1
31+
kind: Gateway
32+
metadata:
33+
name: mcp-gateway
34+
namespace: gateway-namespace
35+
spec:
36+
gatewayClassName: openshift-default
37+
listeners:
38+
- name: http
39+
port: 80
40+
protocol: HTTP
41+
allowedRoutes:
42+
namespaces:
43+
from: All
44+
- name: mcps
45+
hostname: mcp.example.com
46+
port: 8080
47+
protocol: HTTP
48+
allowedRoutes:
49+
namespaces:
50+
from: All
51+
- name: https
52+
hostname: mcp.apps.openshift.example.com
53+
port: 443
54+
protocol: HTTPS
55+
allowedRoutes:
56+
namespaces:
57+
from: All
58+
tls:
59+
certificateRefs:
60+
- group: ''
61+
kind: Secret
62+
name: default-ingress-cert
63+
mode: Terminate
64+
----
65+
+
66+
* The custom resource (CR) is a `Gateway` named `mcp-gateway` that exists in the `gateway-namespace` namespace and has three listeners configured.
67+
* On {ocp}, the `spec.listeners.tls.certificateRefs:` value can specify the `Secret` CR containing the default wildcard certificate for the OpenShift Ingress controller.
68+
+
69+
[IMPORTANT]
70+
====
71+
You must use the `spec.listeners[].name` value in the corresponding `MCPGatewayExtension` CR `spec.targetRef.sectionName:` field.
72+
====
73+
74+
. Optional. Verify the {prodname} `DNSPolicy` CR attachment by checking its status with the following command:
75+
+
76+
[source,terminal,subs="+quotes"]
77+
----
78+
$ oc get dnspolicy _<mcp_dns_policy>_ -n _<gateway_namespace>_ -o wide
79+
----
80+
+
81+
* Replace `_<mcp_dns_policy>_` with the name of your {prodname} `DNSPolicy` CR.
82+
* Replace `_<gateway_namespace>_` with the `Gateway` object namespace.
83+
+
84+
.Example output
85+
[source,text]
86+
----
87+
ACCEPTED: True
88+
----

‎modules/proc-config-mcp-gateway-listener.adoc‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
// Module included in the following assemblies:
2+
//
3+
// *mcp_gateway_install/mcp-gateway-install.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="proc-config-mcp-gateway-listener_{context}"]
7+
= Configuring MCP gateway listeners
8+
9+
[role="_abstract"]
10+
Connect your MCP gateway to your agentic AI systems by appending your `Gateway` custom resource (CR) with your MCP listener information. The MCP listener handles the transport protocol, opens an MCP session on the port, and establishes a security perimeter. You can also add listeners for unencrypted web traffic and secured traffic.
11+
12+
.Prerequisites
13+
14+
* You are logged in to your {ocp} cluster.
15+
* You created a gateway custom resource (CR).
16+
* You installed {mcpg}.
17+
* You configured a gateway API provider.
18+
* Optional. If you are adding a secure listener, you have a TLS certificate to reference. The certificate must be in the same namespace as the `Gateway` CR.
19+
20+
.Procedure
21+
22+
. Add an MCP gateway listener to your `Gateway` CR by appending it with the following command:
23+
+
24+
[source,terminal,subs="+quotes"]
25+
----
26+
$ $ oc patch gateway _<mcp_gateway>_ -n _<gateway_namespace>_ --type='json' -p='[
27+
{
28+
"op": "add",
29+
"path": "/spec/listeners/-",
30+
"value": {
31+
"name": "mcps",
32+
"hostname": "_<mcp.example.com>_",
33+
"port": 8080,
34+
"protocol": "HTTP",
35+
"allowedRoutes": {
36+
"namespaces": {
37+
"from": "All"
38+
}
39+
}
40+
}
41+
}
42+
]'
43+
----
44+
+
45+
* Replace `_<mcp_gateway>_` with the name of your MCP gateway.
46+
* Replace `_<gateway_namespace>_` with the namespace where your `Gateway` object is applied.
47+
* Replace `_<mcp.example.com>_` with the hostname you want to use.
48+
49+
. Verify that your listener is working by running the following command:
50+
+
51+
[source,terminal,subs="+quotes"]
52+
----
53+
$ oc get gateway _<mcp_gateway>_ -n _<gateway_namespace>_ -o yaml
54+
----
55+
+
56+
* Replace `_<mcp_gateway>_` with the name of your MCP gateway deployment.
57+
* Replace `_<gateway_namespace>_` with the namespace where your `Gateway` object is applied.
58+
* The conditions `Accepted: True` and `Programmed: True` are expected in the `status` of the output.
59+
60+
. Add a standard web traffic listener to your `Gateway` CR by appending it with the following command:
61+
+
62+
[source,terminal,subs="+quotes"]
63+
----
64+
$ oc patch gateway _<mcp_gateway>_ -n _<gateway_namespace>_ --type='json' -p='[
65+
{
66+
"op": "add",
67+
"path": "/spec/listeners/-",
68+
"value": {
69+
"name": "http-web",
70+
"port": 80,
71+
"protocol": "HTTP",
72+
"allowedRoutes": {
73+
"namespaces": {
74+
"from": "All"
75+
}
76+
}
77+
}
78+
}
79+
]'
80+
----
81+
+
82+
* Replace `_<mcp_gateway>_` with the name of your MCP gateway.
83+
* Replace `_<gateway_namespace>_` with the namespace where your `Gateway` object is applied.
84+
* The `listener.name` value must be a unique name within the `Gateway` object. In this example, `http-web` is used.
85+
* The `listener.port: 80,` is the standard port for unencrypted web traffic.
86+
* You can add a `hostname` if you want to limit incoming domain names.
87+
88+
. Add a secure listener to your `Gateway` CR by appending it with the following command:
89+
+
90+
[source,terminal,subs="+quotes"]
91+
----
92+
$ oc patch gateway _<mcp_gateway>_ -n _<gateway_namespace>_ --type='json' -p='[
93+
{
94+
"op": "add",
95+
"path": "/spec/listeners/-",
96+
"value": {
97+
"name": "https",
98+
"hostname": "_<mcp.example.com>_",
99+
"port": 443,
100+
"protocol": "HTTPS",
101+
"tls": {
102+
"mode": "Terminate",
103+
"certificateRefs": [
104+
{
105+
"name": "mcp-tls-secret",
106+
"kind": "Secret"
107+
}
108+
]
109+
},
110+
"allowedRoutes": {
111+
"namespaces": {
112+
"from": "All"
113+
}
114+
}
115+
}
116+
}
117+
]'
118+
----
119+
+
120+
* Replace `_<mcp_gateway>_` with the name of your MCP gateway deployment.
121+
* Replace `_<gateway_namespace>_` with the namespace where your `Gateway` object is applied.
122+
* Replace `_<mcp.example.com>_` with the hostname you are targeting.
123+
* The `spec.listeners.tls.certificateRefs.name:` parameter specifies the name of your secret. This example uses `mcp-tls-secret`.
124+
* The `spec.listeners.tls.mode: Terminate` value means that the gateway decrypts the traffic and sends it as plain text to your MCP server. You can specify the mode that you require.
125+
* You must set a `spec.listeners.hostname` so that the relevant certificate is presented to the correct client.
126+
127+
. Check that your certificates are properly linked by running the following command:
128+
+
129+
[source,terminal,subs="+quotes"]
130+
----
131+
$ oc get gateway _<mcp_gateway>_ -n _<gateway_namespace>_ -o jsonpath='{.status.listeners[?(@.name=="https")]}'
132+
----
133+
+
134+
* Replace `_<mcp_gateway>_` with the name of your MCP gateway deployment.
135+
* Replace `_<gateway_namespace>_` with the namespace where your `Gateway` object is applied.
136+
* The `status` message outputs any errors.
137+
138+
.Verification
139+
140+
. Check the status your listeners and related objects by running the following command:
141+
+
142+
[source,terminal,subs="+quotes"]
143+
----
144+
$ oc describe gateway _<mcp_gateway>_ -n _<gateway_namespace>_
145+
----
146+
+
147+
* Replace `_<mcp_gateway>_` with the name of your MCP gateway deployment.
148+
* Replace `_<gateway_namespace>_` with the namespace where your `Gateway` object is applied.
149+
+
150+
.Example output
151+
[source,yaml]
152+
----
153+
# ...
154+
Status:
155+
Listeners:
156+
- Name: http-web
157+
Supported Kinds:
158+
Group: gateway.networking.k8s.io
159+
Kind: HTTPRoute
160+
Conditions:
161+
Last Transition Time: 2026-04-01T...
162+
Message: None
163+
Reason: Programmed
164+
Status: True
165+
Type: Programmed
166+
- Name: https
167+
Conditions:
168+
Reason: ResolvedRefs
169+
Status: True
170+
Type: ResolvedRefs
171+
# ...
172+
Events:
173+
Type Reason Age From Message
174+
Normal Synced 12m gateway-api-controller Successfully synced Gateway configuration
175+
Normal IPAllocated 11m mcp-operator Assigned IP 192.168.1.100 to Gateway
176+
Normal ListenerAccepted 10m gateway-api-controller Listener "http-web" accepted
177+
Normal Programmed 10m gateway-api-controller Gateway has been successfully programmed
178+
# ...
179+
----
180+
+
181+
* The `Events` section of the output can also show port conflicts, problems with your `gatewayClassName:` value, missing routes, and a lack of permissions to read secrets.

0 commit comments

Comments
 (0)