Red Hat Connectivity Link

Understand MCP gateway authentication

When you enable authentication, the Model Context Protocol (MCP) clients can discover your authorization server and complete the authentication flow. The MCP gateway broker component makes OAuth 2.0 Protected Resource Metadata accessible.

You can implement the following actions by using authentication:

Set up the MCP gateway to validate access tokens issued by your identity provider.
Return a 401 error message with authorization server discovery information.
Expose OAuth configuration at /.well-known/oauth-protected-resource.
Enable MCP clients to discover and use your identity provider’s client registration.

The following example uses a Connectivity Link AuthPolicy with Red Hat build of Keycloak as an identity provider. The MCP gateway supports any Istio or Gateway API compatible authentication mechanism.

Additional resources

MCP Authorization specification

Configure MCP gateway authentication with an AuthPolicy

Configure authentication for your MCP gateway by using a Connectivity Link AuthPolicy custom resource (CR) and an identity provider such as Red Hat build of Keycloak.

Note	The MCP gateway supports Istio or Gateway API compatible authorization and authenticatio mechanisms. Use the best solution for your OpenShift Container Platform clusters.

Prerequisites

You installed MCP gateway.
You installed Connectivity Link.
You configured a Gateway object with an mcp listener.
You installed and have ready an identity provider supporting OAuth 2.0 or 2.1, for example, Red Hat build of Keycloak.

Procedure

Add a listener to the Gateway object for your identity provider by using the following command as an example:

$ oc patch gateway <mcp_gateway> -n <gateway_system> --type json -p '[
  {
    "op": "add",
    "path": "/spec/listeners/-",
    "value": {
      "name": "keycloak",
      "hostname": "keycloak.example.com",
      "port": 8002,
      "protocol": "HTTP",
      "allowedRoutes": {
        "namespaces": {
          "from": "Selector",
          "selector": {
            "matchLabels": {
              "kubernetes.io/metadata.name": "keycloak"
            }
          }
        }
      }
    }
  }
]'

Replace <mcp_gateway> with the name of your MCP gateway instance.
Replace <gateway_system> with the namespace of your Gateway object.
Replace the Red Hat build of Keycloak <name>, <hostname>, and <kubernetes.io/metadata.name> with your identity provider information.

Configure the MCP gateway broker component to respond with OAuth discovery information by setting the following environment variables:
```
$ oc set env deployment/<mcp_gateway> \
  OAUTH_RESOURCE_NAME="MCP Server" \
  OAUTH_RESOURCE="http://mcp.example.com:8001/mcp" \
  OAUTH_AUTHORIZATION_SERVERS="http://keycloak.example.com:8002/realms/mcp" \
  OAUTH_BEARER_METHODS_SUPPORTED="header" \
  OAUTH_SCOPES_SUPPORTED="basic,groups,roles,profile" \
  -n <mcp_system>
```
- Replace <mcp_gateway> with the name of your MCP gateway instance.
- Replace <mcp_system> with the namespace where your MCP gateway instance is deployed.
- OAUTH_RESOURCE_NAME: Human-readable name for the Model Context Protocol (MCP) server.
- OAUTH_RESOURCE: Canonical URI of the MCP server that is used for token audience validation.
- OAUTH_AUTHORIZATION_SERVERS: Authorization server URL for client discovery.
- OAUTH_BEARER_METHODS_SUPPORTED: Supported bearer token methods. Valid values are usually header, body, or query.
- OAUTH_SCOPES_SUPPORTED: The OAuth scopes this MCP server supports.
Create an AuthPolicy CR that validates JWT tokens:
Example AuthPolicy CR
```
apiVersion: kuadrant.io/v1
kind: AuthPolicy
metadata:
  name: <mcp_jwt_auth_policy>
  namespace: <gateway_system>
spec:
  targetRef:
    group: gateway.networking.k8s.io
    kind: Gateway
    name: <mcp_gateway>
    sectionName: <mcp>
  defaults:
    when:
      - predicate: "!request.path.contains('/.well-known')"
    rules:
      authentication:
        'keycloak':
          jwt:
            issuerUrl: http://keycloak.example.com:8002/realms/mcp
      response:
        unauthenticated:
          code: 401
          headers:
            'WWW-Authenticate':
              value: Bearer resource_metadata=http://mcp.example.com:8001/.well-known/oauth-protected-resource
          body:
            value: |
              {
                "error": "Unauthorized",
                "message": "Authentication required."
              }
```
- The metadata.name: parameter value is the name of the AuthPolicy CR. Replace <mcp_jwt_auth_policy> as needed.
- The metadata.namespace: parameter value is the gateway namespace. Replace <gateway_system> with the namespace where you created your Gateway object to apply the AuthPolicy CR to the namespace.
- The spec.targetRef.name: parameter value is the name of your MCP gateway. Replace <mcp_gateway> as needed.
- The spec.targetRef.sectionName: parameter value is the target gateway listener. In this example, mcp is used.
- The spec.defaults.when parameter value in this example allows unauthenticated access to /.well-known endpoints.
- The spec.defaults.rules.authentication: parameter defines which tokens to validate and how. In this case, JWT validation validates tokens against the Keycloak OIDC issuer.
- The spec.defaults.rules.response.unauthenticated.headers.'WWW-Authenticate': parameter points clients to OAuth discovery metadata. Replace the resource_metadata= information as required.
- The spec.defaults.rules.response.unauthenticated.body.value: parameter is set with a standard response. This configuration returns a 401 error in an OAuth error format.
Apply the AuthPolicy CR by running the following command:
```
$ oc apply -f <mcp_jwt_auth_policy.yaml>
```
Replace <mcp_jwt_auth_policy.yaml> with the name of your CR.

Verification

Test that the broker now serves OAuth discovery information by checking the protected resource metadata endpoint with the following command:

$ curl http://<mcp.example.com:8001>/.well-known/oauth-protected-resource

Replace the URL with your protected resource information.

Example output

{
  "resource_name": "MCP Server",
  "resource": "http://example.com:8001/mcp",
  "authorization_servers": [
    "http://keycloak.example.com:8002/realms/mcp"
  ],
  "bearer_methods_supported": [
    "header"
  ],
  "scopes_supported": [
    "basic",
    "groups",
    "roles",
    "profile"
  ]
}

Test that protected endpoints now require authentication by running the following command:

$ curl -v http://<mcp.example.com:8001/mcp> \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

Replace <mcp.example.com:8001/mcp> with your endpoint.

Example output

{
  "error": "Unauthorized",
  "message": "Authentication required."
}

A 401 error with WWW-Authenticate header is expected.

Next steps

Control which users can access specific tools by configuring authorization policies.
Connect authenticated external MCP services.