Chapter 2. Observe MCP gateway connections

Procedure

1. Create an AuthPolicy CR for the client-facing listener, mcp, by using the following example:

   Client-facing listener AuthPolicy CR

   apiVersion: kuadrant.io/v1
   kind: AuthPolicy
   metadata:
     name: <audit_auth_client_listener>
     namespace: <gateway_namespace>
   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: https://keycloak.example.com:8002/realms/mcp
         response:
           success:
             headers:
               "x-auth-identity":
                 plain:
                   selector: auth.identity.preferred_username
           unauthenticated:
             code: 401
             headers:
               'WWW-Authenticate':
                 value: Bearer resource_metadata=http://mcp.example.com:8001/.well-known/oauth-protected-resource/mcp
             body:
               value: |
                 {
                   "error": "Unauthorized",
                   "message": "Authentication required."
                 }

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

   • Replace <gateway_namespace> with the namespace where you applied your Gateway object.

     Note

     This mcp listener AuthPolicy CR validates JSON web tokens (JWTs) on client requests and injects the authenticated username as a request header.

2. Apply the client-listener AuthPolicy CR by running the following command:

   $ oc apply -f <audit_auth_client_listener.yaml>

   Replace <audit_auth_client_listener.yaml> with the filename that you used.

3. Create an AuthPolicy CR for the backend-facing listener, mcps, by using the following example:

   Client-facing listener AuthPolicy CR

   apiVersion: kuadrant.io/v1
   kind: AuthPolicy
   metadata:
     name: <audit_auth_backend_listener>
     namespace: <gateway_namespace>
   spec:
     targetRef:
       group: gateway.networking.k8s.io
       kind: Gateway
       name: <mcp_gateway>
       sectionName: mcps
     defaults:
       rules:
         authentication:
           'keycloak':
             jwt:
               issuerUrl: https://keycloak.example.com:8002/realms/mcp
         response:
           success:
             headers:
               "x-auth-identity":
                 plain:
                   selector: auth.identity.preferred_username
           unauthenticated:
             code: 401
             headers:
               'WWW-Authenticate':
                 value: Bearer resource_metadata=http://mcp.example.com:8001/.well-known/oauth-protected-resource/mcp
             body:
               value: |
                 {
                   "error": "Unauthorized",
                   "message": "Authentication required."
                 }

   • Replace <mcp_gateway> with the name of your MCP gateway deployment.
   • Replace <gateway_namespace> with the namespace where you applied your Gateway object.

   • Replace the preferred_username field value with sub or another claim depending on both your identity provider and what you want as the audit identity. For Red Hat build of Keycloak, the preferred_username field value gives a human-readable username but requires the profile scope in the token request.

     Note

     This mcps listener policy validates the same JWT on tool call requests routed to backend servers and injects the identity header there, too.

4. Apply the backend-listener AuthPolicy CR by running the following command:

   $ oc apply -f <audit_auth_backend_listener.yaml>

   Replace <audit_auth_backend_listener.yaml> with the filename that you used.

Procedure

1. Get a token by running the following command:

   $ TOKEN=$(curl -s -X POST "https://keycloak.example.com:8002/realms/mcp/protocol/openid-connect/token" \
     -d "grant_type=password&client_id=mcp-gateway&client_secret=secret&username=mcp&password=mcp&scope=openid+profile" \
     | jq -r '.access_token')

   Adjust this command for your identity provider.

2. Initialize a session by running the following command:

   $ SESSION_ID=$(curl -si http://mcp.example.com:8001/mcp \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"audit-test","version":"0.0.1"}}}' \
     | grep -i 'mcp-session-id:' | awk '{print $2}' | tr -d '\r')

   The expected output is the session ID returned in the response header.

3. Call the headers tool to see which headers reach the backend by running the following command:

   $ curl -s http://mcp.example.com:8001/mcp \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -H "Mcp-Session-Id: $SESSION_ID" \
     -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"test1_headers","arguments":{}}}' \
     | jq '.result.content[0].text' | grep -i "x-auth-identity"

   The expected output is the x-auth-identity header that lists the Keycloak username in the response.

Procedure

1. Create a Telemetry CR in the namespace where your Gateway object is applied by using the following example:

   Example Telemetry CR for audit logs

   apiVersion: telemetry.istio.io/v1
   kind: Telemetry
   metadata:
     name: <mcp_audit_logging>
     namespace: <gateway_namespace>
   spec:
     selector:
       matchLabels:
         gateway.networking.k8s.io/gateway-name: <mcp_gateway>
     accessLogging:
       - providers:
           - name: mcp-json-access-log

   • Replace <mcp_audit_logging> with the name of your audit logging Telemetry CR.
   • Replace <gateway_namespace> with the namespace where you applied your Gateway object.
   • Replace <mcp_gateway> with the name of your MCP gateway deployment.

2. Apply the Telemetry CR by running the following command:

   $ oc apply -f <mcp_audit_logging.yaml>

   Replace <mcp_audit_logging.yaml> with the name of your audit logging YAML.

Verification

1. Verify that your Telemetry CR is applied by running the following command:

   $ oc get telemetry -n <gateway_namespace>

   Replace <gateway_namespace> with the namespace where you applied your Gateway object.

Procedure

1. Make an authenticated tool call by reusing both the token and session ID from the earlier step by running the following command:

   $ curl -s http://mcp.example.com:8001/mcp \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -H "Mcp-Session-Id: $SESSION_ID" \
     -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"test1_greet","arguments":{"name":"audit-test"}}}'

2. Check the Gateway object pod logs for the JSON access log entry by running the following command:

   $ oc logs -n <gateway_namespace> -l gateway.networking.k8s.io/gateway-name=<mcp_gateway> --since=30s \
     | grep '"mcp_method"' | tail -1 | jq .

   • Replace <gateway_namespace> with the namespace where you applied your Gateway object.

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

     Example output

     {
       "timestamp": "2026-05-21T14:23:01.123Z",
       "method": "POST",
       "path": "/mcp",
       "response_code": 200,
       "request_id": "abc-111",
       "traceparent": null,
       "mcp_method": "tools/call",
       "mcp_tool_name": "greet",
       "mcp_server_name": "mcp-test/test-server1",
       "mcp_session_id": "sess-7a3b",
       "mcp_user_id": "mcp",
       "duration_ms": 342,
       "upstream_host": "10.0.1.5:8080",
       "bytes_sent": 1024,
       "bytes_received": 512
     }