Red Hat Connectivity Link

Register external MCP servers

To use external Model Context Protocol (MCP) servers with your MCP gateway, you must configure ingress, create routing resources, and register the server with the MCP gateway. As a best practice, you must also configure security rules.

Create a ServiceEntry for an external MCP server

To register an external Model Context Protocol (MCP) server, you must first make sure that it has an ingress pathway by creating a ServiceEntry custom resource (CR) in your Istio deployment. OpenShift Container Platform 4.19 and newer provides Istio through the Gateway API.

Prerequisites

You completed all of the installation and configuration steps for MCP gateway.
You have the information for the external MCP server you want to connect to.
You installed the OpenShift CLI (oc).
You are using Istio for ingress control.

Procedure

Create a ServiceEntry CR that registers the external server in the Istio service registry by using the following template:
Example ServiceEntry CR
```
apiVersion: networking.istio.io/v1beta1
kind: ServiceEntry
metadata:
  name: <mcp_external_server>
  namespace: <mcp_test>
spec:
  hosts:
  - <api.githubcopilot.com>
  ports:
  - number: 443
    name: https
    protocol: HTTPS
  location: MESH_EXTERNAL
  resolution: DNS
```
- Replace <mcp_external_server> with the name of your external MCP server.
- Replace <mcp_test> with the namespace that the MCP server is in.
- Replace <api.githubcopilot.com> with the host URL of the MCP server.
- Replace any other values as required.
Apply the CR by running the following command:
```
$ oc apply -f <mcp_external_server_se.yaml>
```
Replace <mcp_external_server_se.yaml> with the name of your CR.

Create TLS settings for an external MCP server

To register an external Model Context Protocol (MCP) server, after you create a ServiceEntry custom resource (CR) in your Istio deployment, you must configure your TLS settings with a DestinationRule CR.

Prerequisites

You completed all of the installation and configuration steps for MCP gateway.
You have the information for the external MCP server you want to connect to.
You installed the OpenShift CLI (oc).
You are using Istio for ingress control.
You created a ServiceEntry object.

Procedure

Create a DestinationRule CR that configure your TLS settings by using the following template:
Example DestinationRule CR
```
apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: <mcp_external_server>
  namespace: <mcp_test>
spec:
  host: <api.githubcopilot.com>
  trafficPolicy:
    tls:
      mode: SIMPLE
      sni: <api.githubcopilot.com>
```
- Replace <mcp_external_server> with the name of your external MCP server.
- Replace <mcp_test> with the namespace that the MCP server is in.
- The default TLS mode is SIMPLE. Change it to MUTUAL in high-security environments or use ISTIO_MUTUAL with OpenShift Service Mesh. A value of DISABLE means that TLS is not used.
- Replace <api.githubcopilot.com> with the host URL of the MCP server.
Apply the CR by running the following command:
```
$ oc apply -f <mcp_external_server_dr.yaml>
```
Replace <mcp_external_server_dr.yaml> with the name of your CR.

Create an HTTPRoute for an external MCP server

To use an external Model Context Protocol (MCP) server, you must create an HTTPRoute custom resource (CR) that matches your internal hostname and routes to the external service by using Istio.

Prerequisites

You completed all of the installation and configuration steps for MCP gateway.
You have the information for the external MCP server you want to connect to.
You installed the OpenShift CLI (oc).
You are using Istio for ingress control.
You created ServiceEntry and DestinationRule objects.

Procedure

Create a HTTPRoute CR that routes to the external service by using the following example:
Example HTTPRoute CR
```
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: <mcp_external_server>
  namespace: <mcp_test>
spec:
  parentRefs:
  - group: gateway.networking.k8s.io
    kind: Gateway
    name: <mcp_gateway>
    namespace: <gateway_system>
  hostnames:
  - example.mcp.local
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /mcp
    filters:
    - type: URLRewrite
      urlRewrite:
        hostname: <api.externalhostname.com>
    backendRefs:
    - name: <api.example.com>
      kind: Hostname
      group: networking.istio.io
      port: 443
```
- Replace the metadata.name: field value with the name of your external MCP server.
- Replace the metadata.namespace: field value with the namespace that the MCP server is in.
- Set the spec.parentRefs: fields to match your MCP Gateway object.
- The spec.hostnames: field value is your internal hostname. It must match your *.mcp.local Gateway CR value.
- The spec.rules.matches.path.value: field value is your MCP gateway endpoint. In this example, /mcp is used.
- Replace the value of spec.rules.filters.urlRewrite.hostname: with your external hostname.
- Replace the spec.rules.backendRefs.name: field value with the host URL of the MCP server.
Apply the CR by running the following command:
```
$ oc apply -f <mcp_external_server_httproute.yaml>
```
Replace <mcp_external_server_httproute.yaml> with the name of your CR.

Create a Secret for an external MCP server

To use an external Model Context Protocol (MCP) server, you must create a Secret custom resource (CR) that stores backend API key credentials.

This Secret CR is referenced in your MCPServerRegistration CR in the credentialRef parameter. These resources are for backend API key authentication. The api-key is stored in the config secret and used by the MCP broker component for upstream connections.

Prerequisites

You completed all of the installation and configuration steps for MCP gateway.
You have the information for the external MCP server you want to connect to.
You installed the OpenShift CLI (oc).
You are using Istio for ingress control.
You created ServiceEntry, DestinationRule, and HTTPRoute objects.

Procedure

Create a Secret CR that stores backend API key credentials by using the following example:
Example Secret CR
```
apiVersion: v1
kind: Secret
metadata:
  name: <mcp_backend_auth>
  namespace: <mcp_test>
  labels:
    mcp.kuadrant.io/secret: "true"
    app.kubernetes.io/part-of: mcp-gateway
    env: production
type: Opaque
stringData:
  api-key: <"mcp_prod_12abC34...">
```
- Replace the metadata.name: field value with the name you want to use. Service naming is used in this example.
- Replace the metadata.namespace: field value with the namespace you used in your ServiceEntry object.
- You must use the metadata.labels.mcp.kuadrant.io/secret: "true" field and value. If you do not use this value, the MCP gateway controller cannot see the Secret object.
- The metadata.labels.app.kubernetes.io/part-of: mcp-gateway field and value are optional.
- Replace your stringData.api-key: value with the one you need to use.
Apply the CR by running the following command:
```
$ oc apply -f <mcp_external_server_secret.yaml>
```
Replace <mcp_external_server_secret.yaml> with the name of your CR.

Create an AuthPolicy for an external MCP server

To secure your use of an external Model Context Protocol (MCP) server, creating an AuthPolicy custom resource (CR) to authenticate your sessions is a best practice. The following example uses Kuadrant/Authorino for OAuth authentication and creates an AuthPolicy CR to handle authorization headers.

Note	This step is required if you are using OAuth authentication for your external MCP server. If your external MCP server uses a simple API key, you can use a `credentialRef` in your `MCPServerRegistration` CR instead, and an `AuthPolicy` object is not needed.

Prerequisites

You completed all of the installation and configuration steps for MCP gateway.
You have the information for the external MCP server you want to connect to.
You installed the OpenShift CLI (oc).
You are using Istio for ingress control.
You created ServiceEntry, DestinationRule, and HTTPRoute objects.

Procedure

Create an AuthPolicy CR that handles authorization headers by using the following example:
Example AuthPolicy CR
```
apiVersion: kuadrant.io/v1
kind: AuthPolicy
metadata:
  name: <mcps_auth_policy>
  namespace: <mcp_test>
spec:
  targetRef:
    group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: <mcp_external_server>
  rules:
    response:
      success:
        headers:
          authorization:
            plain:
              expression: 'request.headers["authorization"]'
```
- Replace the metadata.name: field value with the name you want to use. This approach uses service naming.
- Replace the metadata.namespace: field value with the namespace you used in your ServiceEntry object.
- Replace the spec.name: value with the name of your external MCP server route.
- This AuthPolicy CR passes through the Authorization header from the original request.
Apply the CR by running the following command:
```
$ oc apply -f <mcp_external_server_authpolicy.yaml>
```
Replace <mcp_external_server_authpolicy.yaml> with the name of your CR.

Create an MCPServerRegistration for an external MCP server

To use an external Model Context Protocol (MCP) server, you must create an MCPServerRegistration custom resource (CR) that registers your external MCP server with the MCP gateway.

Prerequisites

You completed all of the installation and configuration steps for MCP gateway.
You have the information for the external MCP server you want to connect to.
You installed the OpenShift CLI (oc).
You are using Istio for ingress control.
You created ServiceEntry, DestinationRule, HTTPRoute, and Secret objects.
Recommended: You created an AuthPolicy CR.

Procedure

Create a MCPServerRegistration CR that registers the external MCP server with the MCP gateway by using the following example:
Example MCPServerRegistration CR
```
apiVersion: mcp.kuadrant.io/v1alpha1
kind: MCPServerRegistration
metadata:
  name: <external_mcp_server>
  namespace: <mcp_test>
spec:
  prefix: <"extserver">_
  targetRef:
    group: "gateway.networking.k8s.io"
    kind: "HTTPRoute"
    name: "<mcp_api_key_server_route>"
    namespace: "<mcp_test>"
  credentialRef:
    name: <mcp_backend_secret>
    key: api-key
```
- Replace the metadata.name: field value with the name you want to use.
- Replace the metadata.namespace: field value with the namespace you need to use. If you did not use a ReferenceGrant CR, the value of metadata.namespace: must be the same as the namespace specified in the HTTPRoute object.
- Replace the spec.prefix: field with the value that you want to use 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.
- Replace the value of spec.targetRef.namespace: with the namespace where your HTTPRoute CR is applied.
- The spec.credentialRef: field points to the Secret CR that has credentials for the external MCP server.
  
  Important
  
  A prefix value cannot include spaces or special characters.
Apply the CR by running the following command:
```
$ oc apply -f <mcp_external_server_mcpsr.yaml>
```
Replace <mcp_external_server_mcpsr.yaml> with the name of your CR.

Verify that your external MCP server is ready to use

To verify that an external Model Context Protocol (MCP) server is ready to use, check the status of your MCPServerRegistration custom resource (CR).

Prerequisites

You completed all of the installation and configuration steps for MCP gateway.
You have the information for the external MCP server you want to connect to.
You installed the OpenShift CLI (oc).
You are using Istio for ingress control.
You completed the previous steps to register your MCP server with the MCP gateway.

Procedure

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-ext    extserver   external-mcp-server     /mcp   True    5       ext-server-secret    14m
mcp-test    mcp-server-one    serverone   mcp-api-key-server      /mcp   True    4                            1d
mcp-test    mcp-server-two    servertwo   mcp-generic-route       /mcp   True    7                            2d
mcp-prod    analytics-tools   stats       analytics-route         /mcp   True    3       analytics-secret     5h