Chapter 1. Installing and configuring MCP gateway

Procedure

1. Create the namespace where you want to install MCP gateway by running the following command:

   $ oc create ns <mcp_system>

   Replace the default <mcp_system> with the namespace you want to use.

2. Create and apply the MCP gateway Subscription and OperatorGroup custom resources (CRs) by running the following command:

   $ oc apply -n <mcp_system> -f - <<EOF
   apiVersion: operators.coreos.com/v1alpha1
   kind: Subscription
   metadata:
     name: mcp-gateway
   spec:
     source: redhat-operators
     sourceNamespace: openshift-marketplace
     name: mcp-gateway
     channel: preview
   ---
   apiVersion: operators.coreos.com/v1
   kind: OperatorGroup
   metadata:
     name: mcp-gateway
   spec:
     targetNamespaces:
     - <mcp_system>
   EOF

   Replace <mcp_system> with the namespace you used in the earlier step.

3. Confirm that the MCP gateway installation has finished by running the following commands:

   $ oc wait --for=jsonpath={.status.installPlanRef.name} subscription mcp-gateway -n <mcp_system> --timeout=10s
   ip=$(oc get subscription mcp-gateway -n <mcp_system> -o=jsonpath={.status.installPlanRef.name})

   Replace <mcp_system> with the namespace you used in the earlier step.

   $ oc wait --for=condition=Installed installplan -n <mcp_system> ${ip} --timeout=60s

   • Replace <mcp_system> with the namespace you used in the earlier step.
   • Expect the status of installplan.operators.coreos.com/install-<suffix> when MCP gateway is ready. The name of the install plan has a random suffix, for example, 4rql7.

Verification

1. Wait for the controller to be ready by running the following command:

   $ oc wait csv -n <mcp_system> -l operators.coreos.com/mcp-gateway.<mcp_system>="" --for=jsonpath='{.status.phase}'=Succeeded --timeout=5m

   Replace <mcp_system> with the namespace you used.

Procedure

1. Add an MCP gateway listener to your Gateway CR by appending it with the following command:

   $ $ oc patch gateway <mcp_gateway> -n <gateway_namespace> --type='json' -p='[
     {
       "op": "add",
       "path": "/spec/listeners/-",
       "value": {
         "name": "mcps",
         "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.

2. Verify that your listener is working by running the following command:

   $ 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.

3. Add a standard web traffic listener to your Gateway CR by appending it with the following command:

   $ 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.

4. Add a secure listener to your Gateway CR by appending it with the following command:

   $ 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.

5. Check that your certificates are properly linked by running the following command:

   $ 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

1. Check the status your listeners and related objects by running the following command:

   $ 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

     # ...
     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.

Procedure

1. Create a ReferenceGrant CR by using the following example as a template:

   Example ReferenceGrant CR

   apiVersion: gateway.networking.k8s.io/v1beta1
   kind: ReferenceGrant
   metadata:
     name: <allow_team_a>
     namespace: gateway-system
   spec:
     from:
       - group: mcp.kuadrant.io
         kind: MCPGatewayExtension
         namespace: <team_a>
     to:
       - group: gateway.networking.k8s.io
         kind: Gateway

   • Replace the metadata.name: value with the name that you want to use.
   • Replace the spec.from.namespace: value with the namespace where the MCPGatewayExtension CR is applied.

2. Apply the CR by running the following command:

   $ oc apply -f <allow_team_a>

   Replace <allow_team_a> with name you used.

Procedure

1. Create an MCPGatewayExtension CR by using the following example as a template:

   Example MCPGatewayExtension CR

   apiVersion: mcp.kuadrant.io/v1alpha1
   kind: MCPGatewayExtension
   metadata:
     name: <mcp_gateway_one>
     namespace: <mcp_system>
   spec:
     targetRef:
       group: gateway.networking.k8s.io
       kind: Gateway
       name: <mcp_gateway>
       namespace: <gateway_system>
       sectionName: mcp
     httpRouteManagement: Enabled

   • Replace the metadata.name: parameter value with the name you want to use.
   • Replace the metadata.namespace: parameter value with the namespace you want to use.
   • The spec.targetRef.sectionName: parameter value must be the same as name of the listener on the gateway. In this example, mcp is used.
   • The spec.targetRef.namespace: value must be the namespace of the Gateway object where you created your listener. In this example, <gateway_system> is used.
   • The value of the sectionName: parameter must match the listener name: value defined on your Gateway object in the <gateway_system> namespace. In this example, mcp is used.
   • The default setting of spec.httpRouteManagement: Enabled means automatically maintained HTTPRoute objects to ensure that traffic for discovered MCP tools is correctly routed through the Gateway object.

   • If you require a customized HTTPRoute CR, set the spec.httpRouteManagement: field value to Disabled.

     Important

     In the MCP gateway Technology Preview version, 0.6.0, you must set the spec.httpRouteManagement: field value to Disabled and create a customized managed HTTPRoute CR if you are using OAuth. This is a workaround for a Known Issue. See the Connectivity Link 1.3.3 release notes for details.

2. Apply the CR by running the following command:

   $ oc apply -f <mcp_gateway_one>

   Replace <mcp_gateway_one> with name you used.

3. Wait for the MCPGatewayExtension controller to be ready by running the following command:

   $ oc wait --for=condition=Ready mcpgatewayextension/<mcp_gateway_one> -n <mcp_system>

   • Replace <mcp_gateway_one> with name you used.

   • Replace <mcp_system> with name of your MCP gateway deployment.

     Example successful output

     mcpgatewayextension.mcp.kuadrant.io/mcp-gateway-one condition met

     Example failure output

     error: timed out waiting for the condition on mcpgatewayextensions/mcp-gateway-one

4. Verify that the automatic HTTProute object is created by running the following command:

   $ oc get httproute mcp-gateway-route -n mcp-system

   Example output

   NAME HOSTNAMES AGE
   mcp-gateway-route ["mcp.example.com"] 5m

5. Verify that the Envoy filter exists in the same namespace as the Gateway object by running the following command:

   $ oc get envoyfilter -n <gateway_namespace> -l app.kubernetes.io/managed-by=mcp-gateway-controller

   Replace <gateway_namespace> with the name of your Gateway CR namespace.

Procedure

1. If you have not already done so, disable automatic route creation on your corresponding MCPGatewayExtension object by running the following command:

   $ oc patch mcpgatewayextension -n _<mcp_system>_ _<extension_name>_ \
     --type merge -p '{"spec":{"httpRouteManagement":"Disabled"}}'

   Replace <mcp_system> with the namespace where MCP gateway is installed. Replace <extension_name> with the name of your MCPGatewayExtension CR.

2. Create your customized HTTPRoute CR by using the following template:

   Example customized HTTPRoute CR

   apiVersion: gateway.networking.k8s.io/v1
   kind: HTTPRoute
   metadata:
     name: <mcp_route_custom>
     namespace: <mcp_system>
   spec:
     parentRefs:
       - name: <gateway_name>
         namespace: <gateway_namespace>
         sectionName: <mcp_gateway_listener>
     hostnames:
       - <'mcp.example.com'>
     rules:
       - matches:
           - path:
               type: PathPrefix
               value: /mcp
         filters:
           - type: ResponseHeaderModifier
             responseHeaderModifier:
               add:
                 - name: Access-Control-Allow-Origin
                   value: "*"
                 - name: Access-Control-Allow-Methods
                   value: "GET, POST, PUT, DELETE, OPTIONS, HEAD"
                 - name: Access-Control-Allow-Headers
                   value: "Content-Type, Authorization, Accept, Origin, X-Requested-With"
                 - name: Access-Control-Max-Age
                   value: "3600"
                 - name: Access-Control-Allow-Credentials
                   value: "true"
         backendRefs:
           - name: <mcp_gateway>
             port: 8080
       - matches:
           - path:
               type: PathPrefix
               value: </.well_known/oauth_protected_resource>
         backendRefs:
           - name: <mcp_gateway>
             port: 8080

   • Replace the metadata.name: value with the name that you want to use.
   • Replace the metadata.namespace: value with the namespace that you want to use.
   • Replace the spec.targetRef.sectionName: parameter value with the MCP Gateway object listener.
   • Replace the spec.parentRefs.name: value the name that you want to use.
   • Replace spec.parentRefs.namespace: value with the namespace that you want to use.
   • Replace the spec.hostnames: value or list with the values you want to use.
   • Replace the spec.rules.matches.path.value: value with the URL path where you want to have your Gateway object available.
   • Replace the spec.rules.backend.Refs.name: value with the name of your MCP gateway deployment.

3. Apply the CR by running the following command:

   $ oc apply -f <mcp_route_custom>

   Replace <mcp_route_custom> with the name that you used for your HTTPRoute CR.

4. Delete automatically created HTTPRoute CRs by running the following command:

   $ oc delete httproute mcp-gateway-route  -n mcp-system --ignore-not-found

   Important

   If you do not delete existing HTTPRoute CRs, the Gateway API chooses one based on a spec-defined precedence chain used when multiple HTTPRoute CRs match the same request.