Red Hat Connectivity Link

Understand MCP server registration

You must register your Model Context Protocol (MCP) servers so that each server can be discovered and routed to by the MCP gateway.

When you register a backend MCP server, you must define a prefix in the MCPServerRegistration custom resource (CR) for each tool and prompt name. Prefixing each MCP server’s listed capabilities avoids name collisions with other MCP servers.

The MCP gateway then automatically federates the MCP server’s tools and prompts.

To connect an MCP server to the MCP gateway, you must first create an HTTPRoute CR, and then create an MCPServerRegistration CR for the server that references the route.

When a client calls a tool or requests a prompt, the MCP gateway identifies the target upstream server by the prefix, strips the prefix, then routes the request to the correct MCP server with authentication and authorization through an AuthPolicy CR.

Register an MCP server for use with the MCP gateway

Direct your MCP gateway to discover and route to your Model Context Protocol (MCP) servers by registering them.

To connect each MCP server to the MCP gateway, 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.

Prerequisites

You installed the MCP gateway.
You have a Gateway object configured with your requirements.
You configured a listener for the MCP gateway.
You created an HTTPRoute CR for the MCP gateway.
You created and applied an MCPGatewayExtension CR.
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.
You are logged into an OpenShift Container Platform cluster with an admin role.

Procedure

Create an HTTPRoute CR that routes to your MCP server by using the following template:
Example HTTPRoute CR
```
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: <mcp_api_key_server_route>
  namespace: <mcp_test>
  labels:
    mcp-server: 'true'
spec:
  parentRefs:
    - name: <mcp_gateway>
      namespace: <gateway_system>
  hostnames:
    - 'api-key-server.mcp.local'
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: <mcp_api_key_server>
          port: 9090
```
- For the metadata.name: parameter value, replace <mcp_api_key_server_route> with the name of the http route.
- 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.
- For the spec.parentRefs.name: and spec.parentRefs.namespace: parameter values, use the values from the Gateway CR that you are targeting.
- For the spec.hostnames: parameter value, replace the list with your required internal routing hostname.
- For the spec.rules.backendRefs.name: parameter value, replace <mcp_api_key_server> with your MCP gateway service name.
- For the spec.rules.backendRefs.port: parameter value, replace 9090 with your MCP server port.
Apply the CR by running the following command:
```
$ oc apply -f <mcp_api_key_server_route.yaml>
```
Replace <mcp_api_key_server_route.yaml> with the name of the http route you created.

Create an MCPServerRegistration CR that references your HTTPRoute CR by using the following template:

Example MCPServerRegistration CR

apiVersion: mcp.kuadrant.io/v1alpha1
kind: MCPServerRegistration
metadata:
  name: <mcp_server_one>
  namespace: <mcp_test>
spec:
  prefix: <serverone>_
  targetRef:
    group: "gateway.networking.k8s.io"
    kind: "HTTPRoute"
    name: "<mcp_api_key_server_route>"
    namespace: "<mcp_test>"
  credentialRef:
    name: <mcp_server_one_secret>
    key: api-key

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.
Replace the spec.prefix: field with the value that you want to prefix the tools available with this MCP server.
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.
Replace the spec.targetRef.namespace: field value with the namespace where your HTTPRoute CR is applied. In this example, <mcp_test> is used.
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.

For more information about these parameters, see "Understanding the MCPServerRegistration custom resource."

Important

The prefix field only accepts lowercase letters (a-z), digits (0-9), and underscores (_). The value must start with a letter or digit. This is enforced at the CRD schema level.

Existing MCPServerRegistration CRs with non-conforming prefixes continue to function but cannot be updated. To update such resources, delete and re-create them with a conforming prefix.

Apply the CR by running the following command:
```
$ oc apply -f <mcp_server_one.yaml>
```
Replace <mcp_server_one.yaml> with your MCPServerRegistration CR.

Check the status of your current MCPServerRegistration CR by running the following command:

$ oc get mcpsr -n <mcp_server_one>

Replace <mcp_server_one> with the name of your MCPServerRegistration CR.

Example output

NAMESPACE   NAME            PREFIX      TARGET                     PATH   READY   TOOLS   CREDENTIALS   AGE
mcp-test    my-mcp-server   myserver_   mcp-api-key-server-route   /mcp   True    4                     30s

Check the status of all MCPServerRegistration CRs in the cluster by running the following command:

$ oc get mcpsr -A

Example output

NAMESPACE   NAME              PREFIX      TARGET                  PATH   READY   TOOLS   CREDENTIALS   AGE
mcp-test    mcp-server-one    serverone   mcp-api-key-server      /mcp   True    4                     14m
mcp-test    mcp-server-two    servertwo   mcp-generic-route       /mcp   True    7                     2d
mcp-prod    analytics-tools   stats       analytics-route         /mcp   True    3                     5h

Check on tool discovery status by running the following command:

$ oc get mcpsr -A -o yaml

Example output

apiVersion: v1
items:
- apiVersion: mcp.kuadrant.io/v1alpha1
  kind: MCPServerRegistration
  metadata:
    annotations:
      kubectl.kubernetes.io/last-applied-configuration: |
        {"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"},"prefix":"test1_"}}
    creationTimestamp: "2026-03-31T09:50:26Z"
    finalizers:
    - mcp.kuadrant.io/finalizer
    generation: 1
    labels:
      mcp.kuadrant.io/managed: "true"
    name: test-server1
    namespace: mcp-test
    resourceVersion: "302234"
    uid: d9603011-2e0f-4f3f-88d6-eda986f365d1
  spec:
    path: /mcp
    targetRef:
      group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: mcp-server1-route
    prefix: test1_
  status:
    conditions:
    - lastTransitionTime: "2026-04-07T08:49:53Z"
      message: server added successfully. Total tools added 5
      reason: Ready
      status: "True"
      type: Ready
    discoveredTools: 5
kind: List
metadata:
  resourceVersion: "

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.

Understand the MCPServerRegistration custom resource

You can explore the required parts and values for an MCPServerRegistration custom resource (CR) by studying the references contained here.

Table 1. MCPServerRegistration
Field	Type	Required	Description
`spec`	MCPServerRegistrationSpec	Yes	The specification for the `MCPServerRegistration` CR
`status`	MCPServerRegistrationStatus	No	The status for the CR

Table 2. MCPServerRegistrationSpec
Field	Type	Required	Description
`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.
`prefix`	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.
`path`	String	No	The URL path where the MCP server endpoint is exposed. Default value is `/mcp`.
`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.

Table 3. TargetReference
Field	Type	Required	Description
`group`	String	No	Group of the target resource. Default value is `gateway.networking.k8s.io`.
`kind`	String	No	Kind of the target resource. Default value is `HTTPRoute`.
`name`	String	Yes	Name of the target `HTTPRoute` object.
`namespace`	String	No	Namespace of the target resource. Defaults to same namespace.

Table 4. SecretReference
Field	Type	Required	Description
`name`	String	Yes	Name of the `Secret` CR.
`key`	String	No	Key within the `Secret` CR that has the credential value. Default value is `token`.

Table 5. MCPServerRegistrationStatus
Field	Type	Description
`conditions`	Kubernetes meta/v1.Condition	List of conditions that define the status of the Kubernetes resource.
`discoveredTools`	Integer	Number of tools discovered from this `MCPServerRegistration` CR.

Verify an MCP server registration

You can test that your Model Context Protocol (MCP) server tools are available through the MCP gateway by starting a session and listing available tools and prompts.

Prerequisites

You completed all MCP gateway installation and configuration steps.
You registered the MCP server you want to verify.

Procedure

Connect to the MCP gateway and initialize a session to dump response headers to a file by running the following command:

$ curl -s -D /tmp/mcp_headers -X POST http://_<example.com>_/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-11-25", "capabilities": {}, "clientInfo": {"name": "test-client", "version": "1.0.0"}}}'

Replace <example.com> with your URL and port.

Extract the MCP session ID from the dumped response headers by running the following command:

$ SESSION_ID=$(grep -i "mcp-session-id:" /tmp/mcp_headers | cut -d' ' -f2 | tr -d '\r') \
echo "MCP Session ID: $SESSION_ID"

List the tools using the session ID by running the following command:

$ curl -X POST http://<example.com>/mcp \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

Replace <example.com> with your URL and port.

Expected output: Your MCP server tools are listed in the response, prefixed with the prefix value you configured in the MCPServerRegistration CR.

Verify that your MCP server prompts are also available by running the following command:

# Use the same SESSION_ID from the previous step
curl -X POST http://_<example.com>_/mcp \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{"jsonrpc": "2.0", "id": 3, "method": "prompts/list"}'

Replace <example.com> with your URL and port.

Expected output: Your MCP server prompts are listed in the response and are prefixed with the prefix value you configured in the MCPServerRegistration CR.

Retrieve a specific prompt by using the prompts/get method with the prefixed name as shown in the following command:

$ curl -X POST http://_<example.com>_/mcp \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "prompts/get",
    "params": {
      "name": "myserver_gh_pr_review",
      "arguments": {
        "pr_number": "42"
      }
    }
  }'

Replace <example.com> with your URL and port.

Clean up by running the following command:
```
$ rm -f /tmp/mcp_headers
```