Red Hat Connectivity Link

Troubleshoot isolated MCP gateway deployments

You can troubleshoot common issues with isolated MCP gateway deployments, including MCPGatewayExtension status errors, MCPServerRegistration issues, and empty configuration secrets.

Troubleshoot an MCPGatewayExtension ReferenceGrantRequired status

If an MCPGatewayExtension custom resource (CR) targets a Gateway object in a different namespace and no ReferenceGrant CR exists, the extension shows a ReferenceGrantRequired condition.

Prerequisites

You installed OpenShift CLI (oc).
You deployed isolated MCP gateway instances.

Procedure

Check the status of the MCPGatewayExtension CR by running the following command:
```
$ oc get mcpgatewayextension -n <namespace> -o yaml
```
Replace <namespace> with the namespace where the MCPGatewayExtension CR is applied.

Look for the following condition in the output:

conditions:
  - type: Ready
    status: "False"
    reason: ReferenceGrantRequired
    message: "invalid: ReferenceGrant required in %s to allow cross-namespace reference from %s"

Create a ReferenceGrant CR in the Gateway object namespace:
```
apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: <team_a_refgrant>
  namespace: <gateway_namespace>
spec:
  from:
    - group: mcp.kuadrant.io
      kind: MCPGatewayExtension
      namespace: <team_namespace>
  to:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: <team_a_gateway>
```
- Replace the metadata.name value with the name of your team.
- Replace the metadata.namespace value with the namespace where the Gateway object is applied.
- Replace the spec.from.namespace value with the namespace where the MCPGatewayExtension CR is applied.
- Replace the spec.to.name value with the name of the team Gateway object.

Verify the MCPGatewayExtension CR is ready by running the following command:

$ oc wait --for=condition=Ready mcpgatewayextension/<extension_name> -n <namespace> --timeout=60s

Troubleshooting an MCPGatewayExtension InvalidMCPGatewayExtension status

If an MCPGatewayExtension custom resource (CR) shows an InvalidMCPGatewayExtension status, the target Gateway object does not exist or there is a conflict with another extension.

Prerequisites

You installed OpenShift CLI (oc).
You deployed isolated MCP gateway instances.

Procedure

Verify that the target Gateway object exists by running the following command:
```
$ oc get gateway <gateway_name> -n <gateway_namespace>
```
- Replace <gateway_name> with the name of the Gateway object.
- Replace <gateway_namespace> with the namespace where the Gateway object is applied.
Check for conflicting MCPGatewayExtension CRs that target the same Gateway object by running the following command:
```
$ oc get mcpgatewayextension -A
```
Only one MCPGatewayExtension CR can target a given Gateway object. If multiple extensions target the same Gateway object, the controller marks newer ones as conflicted. The oldest extension by creation timestamp takes precedence.
If a conflict exists, update the newer MCPGatewayExtension CR to target a different Gateway object, or delete the conflicting extension.

Troubleshooting an MCPServerRegistration NotReady status

If an MCPServerRegistration custom resource (CR) shows a NotReady status, the registration cannot find a valid MCPGatewayExtension CR for the Gateway object that its HTTPRoute CR is attached to.

MCPServerRegistration CRs are processed only when a valid MCPGatewayExtension CR exists for the Gateway object that their HTTPRoute CR is attached to.

Prerequisites

You installed OpenShift CLI (oc).
You deployed isolated MCP gateway instances.

Procedure

Check the status of the MCPServerRegistration CR by running the following command:
```
$ oc get mcpserverregistration -n <namespace> -o yaml
```
Replace <namespace> with the namespace where the MCPServerRegistration CR is applied.
Verify the following conditions:
1. The HTTPRoute CR exists and references the correct Gateway object, and its status is accepted.
2. An MCPGatewayExtension CR exists that targets the same Gateway object.
3. The MCPGatewayExtension CR is in Ready state by running the following command:
  $ oc get mcpgatewayextension -n <namespace>

Troubleshooting an empty configuration secret

If the configuration Secret object exists but contains no MCP server entries, the MCPServerRegistration custom resources (CRs) might not be in a Ready state.

Prerequisites

You installed OpenShift CLI (oc).
You deployed isolated MCP gateway instances.

Procedure

Check the contents of the configuration Secret object by running the following command:
```
$ oc get secret mcp-gateway-config -n <namespace> -o jsonpath='{.data.config\.yaml}' | base64 -d
```
Replace <namespace> with the namespace where the MCPGatewayExtension CR is applied.
Verify that MCPServerRegistration CRs exist and are in Ready state by running the following command:
```
$ oc get mcpserverregistration -n <namespace>
```
If no MCPServerRegistration CRs exist or none are in Ready state, register MCP servers for this gateway instance.