Skip to content

OSDOCS-17693: adds install to MCP gateway docs #109364

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ShaunaDiaz wants to merge 1 commit into
base: mcp-gateway-docs-tp
Choose a base branch
from
Open

OSDOCS-17693: adds install to MCP gateway docs #109364

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 0 additions & 2 deletions _topic_maps/_topic_map.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,8 +55,6 @@ Name: Installing the MCP gateway
Dir: mcp_gateway_install
Distros: rhcl
Topics:
- Name: Getting started with the MCP gateway
File: mcp-gateway-get-started
- Name: Installing MCP gateway
File: mcp-gateway-install
---
Expand Down
8 changes: 0 additions & 8 deletions mcp_gateway_install/mcp-gateway-get-started.adoc
View file
Open in desktop

This file was deleted.

28 changes: 26 additions & 2 deletions mcp_gateway_install/mcp-gateway-install.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,32 @@
:_mod-docs-content-type: ASSEMBLY
include::_attributes/attributes.adoc[]
[id="mcp-gateway-install"]
= Installing {mcpg}
= Installing and configuring {mcpg}
:context: mcp-gateway-get-install

[role="_abstract"]
FPO assembly
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.

Comment thread
ShaunaDiaz marked this conversation as resolved.
:FeatureName: {mcpg}

include::snippets/technology-preview.adoc[leveloffset=+1]

include::modules/proc-mcp-gateway-install-olm.adoc[leveloffset=+1]

include::modules/proc-config-mcp-gateway-gateway.adoc[leveloffset=+1]

include::modules/proc-config-mcp-gateway-listener.adoc[leveloffset=+1]

include::modules/con-mcp-gateway-install-olm-ext-cr.adoc[leveloffset=+1]

include::modules/ref-mcp-gateway-auto-route.adoc[leveloffset=+2]

include::modules/proc-mcp-gateway-referencegrant.adoc[leveloffset=+1]

include::modules/proc-mcp-gateway-install-olm-ext-cr.adoc[leveloffset=+1]

include::modules/con-mcp-gateway-dns-management.adoc[leveloffset=+1]

include::modules/proc-mcp-gateway-custom-route.adoc[leveloffset=+1]

include::modules/proc-mcp-gateway-config-verify.adoc[leveloffset=+1]
16 changes: 16 additions & 0 deletions modules/con-mcp-gateway-dns-management.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
// Module included in the following assemblies:
//
// *mcp_gateway_install/mcp-gateway-install.adoc

:_mod-docs-content-type: CONCEPT
[id="con-dns-management-mcp-gateway_{context}"]
= DNS management with the MCP gateway

[role="_abstract"]
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.
Comment thread
ShaunaDiaz marked this conversation as resolved.

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.

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.

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.
33 changes: 33 additions & 0 deletions modules/con-mcp-gateway-install-olm-ext-cr.adoc
View file
Open in desktop
Comment thread
ShaunaDiaz marked this conversation as resolved.
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
// Module included in the following assemblies:
//
// *mcp_gateway_install/mcp-gateway-install.adoc

:_mod-docs-content-type: CONCEPT
[id="con-mcp-gateway-install-olm-ext-cr_{context}"]
= Understanding the MCPGatewayExtension custom resource

[role="_abstract"]
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:

* Defines which `Gateway` object the MCP gateway instance is responsible for.
* Determines where configuration `Secret` objects are created.
* Enables isolation by allowing multiple MCP gateway instances in different namespaces to target different `Gateway` objects.

[IMPORTANT]
====
Each namespace can only have one `MCPGatewayExtension` CR.
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.
====

Automatic route creation::

The `MCPGatewayExtension` controller automatically creates an `HTTPRoute` CR named `mcp-gateway-route`. The automatically created `HTTPRoute` CR has the following characteristics:

* Routes `/mcp` traffic to the `mcp-gateway` broker service on port `8080`
* Uses the `hostname` from the `Gateway` listener. Wildcards such as `*.example.com` become `mcp.example.com`
* References the target gateway with the correct `sectionName`
* Is owned by the `MCPGatewayExtension` controller and is cleaned up automatically if the controller is deleted

Custom route creation::

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.
88 changes: 88 additions & 0 deletions modules/proc-config-mcp-gateway-gateway.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
// Module included in the following assemblies:
//
// *mcp_gateway_install/mcp-gateway-install.adoc

:_mod-docs-content-type: PROCEDURE
[id="proc-config-mcp-gateway-gateway_{context}"]
= Creating a Gateway object for your MCP gateway

[role="_abstract"]
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.

[TIP]
====
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.
====

.Prerequisites

* You installed {ocp}.
* You installed {oc-first}.
* You installed the {mcpg} Operator.

.Procedure

* Create a `Gateway` object by using the following example as a template:
+
.Example Gateway CR with listeners
[source,yaml]
----
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: mcp-gateway
namespace: gateway-namespace
spec:
gatewayClassName: openshift-default
listeners:
- name: http
port: 80
protocol: HTTP
allowedRoutes:
namespaces:
from: All
- name: mcp
hostname: mcp.example.com
port: 8080
protocol: HTTP
allowedRoutes:
namespaces:
from: All
- name: https
hostname: mcp.apps.openshift.example.com
port: 443
protocol: HTTPS
allowedRoutes:
namespaces:
from: All
tls:
certificateRefs:
- group: ''
kind: Secret
name: default-ingress-cert
mode: Terminate
----
+
* The custom resource (CR) is a `Gateway` named `mcp-gateway` that exists in the `gateway-namespace` namespace and has three listeners configured.
* On {ocp}, the `spec.listeners.tls.certificateRefs:` value can specify the `Secret` CR containing the default wildcard certificate for the OpenShift Ingress controller.
+
[IMPORTANT]
====
You must use the `spec.listeners[].name` value in the corresponding `MCPGatewayExtension` CR `spec.targetRef.sectionName:` field.
====

. Optional. Verify the {prodname} `DNSPolicy` CR attachment by checking its status with the following command:
+
[source,terminal,subs="+quotes"]
----
$ oc get dnspolicy _<mcp_dns_policy>_ -n _<gateway_namespace>_ -o wide
----
+
* Replace `_<mcp_dns_policy>_` with the name of your {prodname} `DNSPolicy` CR.
* Replace `_<gateway_namespace>_` with the `Gateway` object namespace.
+
.Example output
[source,text]
----
ACCEPTED: True
----
181 changes: 181 additions & 0 deletions modules/proc-config-mcp-gateway-listener.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,181 @@
// Module included in the following assemblies:
//
// *mcp_gateway_install/mcp-gateway-install.adoc

:_mod-docs-content-type: PROCEDURE
[id="proc-config-mcp-gateway-listener_{context}"]
= Configuring MCP gateway listeners

[role="_abstract"]
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.

.Prerequisites

* You are logged in to your {ocp} cluster.
* You created a gateway custom resource (CR).
* You installed {mcpg}.
* You configured a gateway API provider.
* 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.

.Procedure

. Add an MCP gateway listener to your `Gateway` CR by appending it with the following command:
+
[source,terminal,subs="+quotes"]
----
$ $ oc patch gateway _<mcp_gateway>_ -n _<gateway_namespace>_ --type='json' -p='[
{
"op": "add",
"path": "/spec/listeners/-",
"value": {
"name": "mcp",
"hostname": "_<mcp.example.com>_",
"port": 8080,
"protocol": "HTTP",
"allowedRoutes": {
"namespaces": {
"from": "All"
}
}
}
}
]'
----
+
* Replace `_<mcp_gateway>_` with the name of your MCP gateway.
* Replace `_<gateway_namespace>_` with the namespace where your `Gateway` object is applied.
* Replace `_<mcp.example.com>_` with the hostname you want to use.

. Verify that your listener is working by running the following command:
+
[source,terminal,subs="+quotes"]
----
$ oc get gateway _<mcp_gateway>_ -n _<gateway_namespace>_ -o yaml
----
+
* Replace `_<mcp_gateway>_` with the name of your MCP gateway deployment.
* Replace `_<gateway_namespace>_` with the namespace where your `Gateway` object is applied.
* The conditions `Accepted: True` and `Programmed: True` are expected in the `status` of the output.

. Add a standard web traffic listener to your `Gateway` CR by appending it with the following command:
+
[source,terminal,subs="+quotes"]
----
$ oc patch gateway _<mcp_gateway>_ -n _<gateway_namespace>_ --type='json' -p='[
{
"op": "add",
"path": "/spec/listeners/-",
"value": {
"name": "http-web",
"port": 80,
"protocol": "HTTP",
"allowedRoutes": {
"namespaces": {
"from": "All"
}
}
}
}
]'
----
+
* Replace `_<mcp_gateway>_` with the name of your MCP gateway.
* Replace `_<gateway_namespace>_` with the namespace where your `Gateway` object is applied.
* The `listener.name` value must be a unique name within the `Gateway` object. In this example, `http-web` is used.
* The `listener.port: 80,` is the standard port for unencrypted web traffic.
* You can add a `hostname` if you want to limit incoming domain names.

. Add a secure listener to your `Gateway` CR by appending it with the following command:
+
[source,terminal,subs="+quotes"]
----
$ oc patch gateway _<mcp_gateway>_ -n _<gateway_namespace>_ --type='json' -p='[
{
"op": "add",
"path": "/spec/listeners/-",
"value": {
"name": "https",
"hostname": "_<mcp.example.com>_",
"port": 443,
"protocol": "HTTPS",
"tls": {
"mode": "Terminate",
"certificateRefs": [
{
"name": "mcp-tls-secret",
"kind": "Secret"
}
]
},
"allowedRoutes": {
"namespaces": {
"from": "All"
}
}
}
}
]'
----
+
* Replace `_<mcp_gateway>_` with the name of your MCP gateway deployment.
* Replace `_<gateway_namespace>_` with the namespace where your `Gateway` object is applied.
* Replace `_<mcp.example.com>_` with the hostname you are targeting.
* The `spec.listeners.tls.certificateRefs.name:` parameter specifies the name of your secret. This example uses `mcp-tls-secret`.
* 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.
* You must set a `spec.listeners.hostname` so that the relevant certificate is presented to the correct client.

. Check that your certificates are properly linked by running the following command:
+
[source,terminal,subs="+quotes"]
----
$ oc get gateway _<mcp_gateway>_ -n _<gateway_namespace>_ -o jsonpath='{.status.listeners[?(@.name=="https")]}'
----
+
* Replace `_<mcp_gateway>_` with the name of your MCP gateway deployment.
* Replace `_<gateway_namespace>_` with the namespace where your `Gateway` object is applied.
* The `status` message outputs any errors.

.Verification

. Check the status your listeners and related objects by running the following command:
+
[source,terminal,subs="+quotes"]
----
$ oc describe gateway _<mcp_gateway>_ -n _<gateway_namespace>_
----
+
* Replace `_<mcp_gateway>_` with the name of your MCP gateway deployment.
* Replace `_<gateway_namespace>_` with the namespace where your `Gateway` object is applied.
+
.Example output
[source,yaml]
----
# ...
Status:
Listeners:
- Name: http-web
Supported Kinds:
Group: gateway.networking.k8s.io
Kind: HTTPRoute
Conditions:
Last Transition Time: 2026-04-01T...
Message: None
Reason: Programmed
Status: True
Type: Programmed
- Name: https
Conditions:
Reason: ResolvedRefs
Status: True
Type: ResolvedRefs
# ...
Events:
Type Reason Age From Message
Normal Synced 12m gateway-api-controller Successfully synced Gateway configuration
Normal IPAllocated 11m mcp-operator Assigned IP 192.168.1.100 to Gateway
Normal ListenerAccepted 10m gateway-api-controller Listener "http-web" accepted
Normal Programmed 10m gateway-api-controller Gateway has been successfully programmed
# ...
----
+
* 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.
Loading