内容

# MCP on Kubernetes with agentgateway + JWT Auth This project demonstrates a local, MCP (Model Context Protocol) security pattern: > Protect an MCP server behind **agentgateway**, require a valid OAuth/JWT access token, and keep the OAuth client secret out of the MCP host configuration file. This demo uses **Auth0** as the OAuth 2.0/OIDC authorization server, but the pattern is vendor-neutral. Any authorization server or identity provider that supports the OAuth 2.0 client credentials grant and publishes signing keys through a JWKS endpoint can be used. ### Tested on :apple: `MacOS` In this setup: - An MCP server (`@modelcontextprotocol/server-everything`) runs inside a local **minikube** Kubernetes cluster. - **agentgateway** acts as an MCP-aware gateway in front of the server. - **Claude Code** acts as the MCP host. - A local wrapper script retrieves the OAuth client secret from the **macOS Keychain** at runtime. - The MCP launcher exchanges the client credentials for a short-lived JWT access token from the authorization server. - **supergateway** bridges Claude Code's stdio MCP connection to the HTTP MCP endpoint exposed through agentgateway. - agentgateway validates the JWT before forwarding MCP traffic to the backend MCP server. The result: the MCP server is not directly exposed as an unauthenticated tool endpoint. Requests must pass through the gateway with a valid bearer token before reaching the MCP server. > This is a headless machine-to-machine pattern. It authenticates the MCP host/application, not an individual end user. --- ## What This Demonstrates This project is useful for learning how to: - Put a gateway enforcement point in front of an MCP server. - Use OAuth 2.0 client credentials for headless MCP access. - Use a standards-based token endpoint to obtain a JWT access token. - Obtain a JWKS set and use as the source of public signing keys for JWT validation. - Validate JWTs at agentgateway before proxying MCP traffic. - Keep client secrets out of `.mcp.json` by retrieving them from macOS Keychain at runtime. - Run an HTTP-based MCP server behind Kubernetes Gateway API resources. - Bridge a local stdio MCP host to an HTTP MCP endpoint using `supergateway`. ## Identity Provider Requirements Auth0 is used in this repo because it is easy to set up for a local demo. It is not required by the pattern. The identity provider or authorization server needs to provide: - An **OAuth 2.0 token endpoint** that supports the `client_credentials` grant. - A **JWT access token** issued for the MCP gateway audience. - A **JWKS endpoint** that publishes the public signing keys used to validate the JWT. - Stable `issuer` and `audience` values that agentgateway can validate. Examples of suitable providers include Auth0, Microsoft Entra ID, Okta, Keycloak, Ping Identity, or another OAuth 2.0/OIDC-compatible authorization server. > The environment variable names in this repo use `AUTH0_*` because the demo was built with Auth0. For another provider, you can either reuse those variable names or rename them to something more generic, such as `OIDC_DOMAIN`, `OAUTH_CLIENT_ID`, and `OAUTH_AUDIENCE`. ## What This Does Not Demonstrate This is intentionally scoped. It does **not** demonstrate: - Per-user delegated authorization. - User identity passthrough. - End-user consent flows. - Production-grade secret rotation. - Enterprise managed identity or workload identity. - Full MCP policy enforcement, such as per-tool authorization or data loss prevention. - Remote JWKS fetching in agentgateway v1.1.0 for an external HTTPS JWKS endpoint over an ExternalName Service. For production, prefer workload identity, managed identity, or `private_key_jwt` where possible instead of a long-lived client secret. --- ## Architecture ```mermaid sequenceDiagram participant CC as Claude Code (MCP host) participant W as mcp-client-auth0-wrapper.zsh participant KC as macOS Keychain participant S as mcp-client.sh participant A0 as OAuth Token Endpoint (Auth0 in this demo) participant SG as supergateway (stdio-to-HTTP bridge) participant AG as agentgateway (Kubernetes) participant MS as mcp-server-everything (Kubernetes) CC->>W: Spawn configured MCP server command W->>KC: Read OAuth client_secret using AUTH0_SECRET_NAME KC-->>W: client_secret W->>S: exec mcp-client.sh (AUTH0_CLIENT_SECRET in env) S->>A0: POST /oauth/token grant_type=client_credentials A0-->>S: JWT access token S->>SG: exec supergateway --streamableHttp MCP_ENDPOINT --header "Authorization: Bearer <token>" loop MCP calls CC->>SG: JSON-RPC over stdio SG->>AG: POST /mcp Authorization: Bearer <JWT> Note over AG: JWKS loaded from inline jwt-policy.yaml Remote JWKS scaffold included for future use AG->>AG: Verify JWT signature, issuer, audience, expiry alt JWT valid AG->>MS: Forward MCP request MS-->>AG: MCP result AG-->>SG: 200 OK + result SG-->>CC: JSON-RPC response else JWT invalid or missing AG-->>SG: 401 authentication failure SG-->>CC: error end end ``` --- ## Prerequisites | Tool | Version used | Install | | -------------- | ------------------------------------- | ---------------------------------------- | | Docker Desktop | 28.x+ | https://docs.docker.com/get-docker/ | | minikube | 1.38.x+ | https://minikube.sigs.k8s.io/docs/start/ | | kubectl | 1.36.x+ | https://kubernetes.io/docs/tasks/tools/ | | helm | 4.x+ | https://helm.sh/docs/intro/install/ | | Node.js + npx | 22.x+ | https://nodejs.org/ | | jq | current | `brew install jq` | | Auth0 account | free tier is sufficient for this demo | https://auth0.com | > **macOS only:** this repo stores the OAuth client secret in the macOS Keychain. The wrapper script uses the `security` CLI, which ships with macOS. --- ## Project Structure ```text . |-- README.md |-- .mcp.json # Claude Code MCP server config |-- config/ | `-- claude_desktop_config.json # Claude Desktop MCP config, no-auth variant |-- scripts/ | |-- mcp-client-auth0-wrapper.zsh # Reads secret from Keychain, execs mcp-client.sh | |-- mcp-client.sh # Fetches Auth0 JWT, launches supergateway | |-- New-JwtPolicyYaml.ps1 # Generates jwt-policy.yaml from live JWKS (PowerShell) | |-- new_jwt_policy_yaml.py # Generates jwt-policy.yaml from live JWKS (Python) | `-- security_testing/ | `-- Test-JwtPolicy.ps1 # JWT policy test suite (PowerShell) `-- k8s/ |-- mcp-server/ | |-- deployment.yaml # MCP server pod using node:22-alpine + mcp-proxy | `-- service.yaml # ClusterIP with appProtocol: agentgateway.dev/mcp `-- agentgateway/ |-- gateway.yaml # Gateway listener on port 80 |-- backend.yaml # AgentgatewayBackend selecting the MCP service |-- httproute.yaml # HTTPRoute wiring Gateway -> Backend |-- jwt-policy.yaml # AgentgatewayPolicy enforcing JWT in Strict mode `-- auth0-jwks-service.yaml # ExternalName Service scaffold for future remote JWKS use ``` --- ## Step 1 - Identity Provider Setup (Auth0 Example) This demo uses Auth0 as the authorization server. The same pattern works with any OAuth 2.0/OIDC-compatible provider that can issue JWT access tokens and publish signing keys through JWKS. For a different provider, create the equivalent of: - a protected API/resource representing the MCP gateway audience - a machine-to-machine OAuth client - a token endpoint that supports `client_credentials` - a JWKS endpoint for JWT signature validation ### 1.1 Create an API In the Auth0 dashboard, create a new **API**: | Field | Value | | --------------------- | --------------------- | | Name | `MCP Gateway` | | Identifier / Audience | `https://mcp.gateway` | | Signing Algorithm | RS256 | ### 1.2 Create a Machine-to-Machine Application Create a new **Machine to Machine** application and authorize it against the API you just created. Note down: - **Domain** - for example, `your-tenant.us.auth0.com` - **Client ID** - **Client Secret** ### 1.3 Generate jwt-policy.yaml agentgateway v1.1.0 does not support pointing its JWT policy at a remote JWKS URI or an OpenID Connect well-known configuration URI. It cannot fetch public keys from `https://idp.example.com/.well-known/jwks.json` or `/.well-known/openid-configuration` at runtime. The signing keys must be embedded directly in the `jwt-policy.yaml` manifest under `jwks.inline`. This means you cannot simply reference your identity provider's JWKS endpoint in the policy. You must fetch the keys yourself and embed them in the manifest. Two scripts are provided to automate exactly that: each one fetches the public keys from your identity provider, constructs the full `AgentgatewayPolicy` manifest, and writes it to disk. Run the script once to generate the file, then re-run it whenever your identity provider rotates its signing keys. Use whichever script fits your environment — they produce identical output. #### PowerShell — `scripts/New-JwtPolicyYaml.ps1` Requires the `powershell-yaml` and `PSJsonWebToken` modules: ```powershell Install-Module powershell-yaml, PSJsonWebToken ``` Dot-source the file to load the function, then call it: ```powershell . ./scripts/New-JwtPolicyYaml.ps1 New-JwtPolicyYaml ` -Uri "https://<your-domain>/.well-known/openid-configuration" ` -Issuer "https://<your-domain>/" ` -Audiences "https://mcp.gateway" ` -OutputPath ./k8s/agentgateway/jwt-policy.yaml ``` `-Uri` accepts either a direct JWK Set URI (`.well-known/jwks.json`) or an OpenID Connect discovery document (`.well-known/openid-configuration`). The function resolves `jwks_uri` automatically when the discovery document form is used. #### Python — `scripts/new_jwt_policy_yaml.py` Requires Python 3 and PyYAML: ```bash pip install pyyaml ``` ```bash python3 scripts/new_jwt_policy_yaml.py \ --uri "https://<your-domain>/.well-known/openid-configuration" \ --issuer "https://<your-domain>/" \ --audiences "https://mcp.gateway" \ --output-path ./k8s/agentgateway/jwt-policy.yaml ``` Like the PowerShell version, `--uri` accepts either a JWKS URI or an OpenID Connect discovery document and follows `jwks_uri` automatically. The generated file is applied to the cluster in Step 5. --- ## Step 2 - Store the Client Secret in macOS Keychain The OAuth client secret is **not stored in `.mcp.json`**. The wrapper script retrieves it at runtime using the macOS `security` CLI. Run this once: ```bash security add-generic-password \ -a "$USER" \ -s <your-secret-name> \ -w "YOUR_CLIENT_SECRET_HERE" \ -U ``` - `-s` sets the service name. This must match `AUTH0_SECRET_NAME` in `.mcp.json`. - `-a` sets the account to your macOS username. - `-w` sets the secret value. - `-U` updates the existing Keychain item if it already exists. To verify it was stored: ```bash security find-generic-password \ -a "$USER" \ -s <your-secret-name> \ -w ``` --- ## Step 3 - Start minikube ```bash minikube start --driver=docker --cpus=4 --memory=4096 ``` --- ## Step 4 - Install agentgateway ```bash # Kubernetes Gateway API CRDs kubectl apply --server-side \ -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.0/standard-install.yaml # agentgateway CRDs helm upgrade -i --create-namespace \ --namespace agentgateway-system \ --version v1.1.0 \ agentgateway-crds oci://cr.agentgateway.dev/charts/agentgateway-crds # agentgateway control plane helm upgrade -i \ -n agentgateway-system \ --version v1.1.0 \ agentgateway oci://cr.agentgateway.dev/charts/agentgateway # Verify all pods reach Running kubectl get pods -n agentgateway-system ``` --- ## Step 5 - Apply Kubernetes Manifests ### 5.1 MCP Server Deployment `k8s/mcp-server/deployment.yaml` runs the reference MCP server inside the cluster using `mcp-proxy` to expose it over HTTP: ```yaml apiVersion: apps/v1 kind: Deployment metadata: name: mcp-server-everything namespace: agentgateway-system spec: replicas: 1 selector: matchLabels: app: mcp-server-everything template: metadata: labels: app: mcp-server-everything spec: containers: - name: mcp-server image: node:22-alpine command: ["npx", "-y", "mcp-proxy", "--port", "8080", "--", "npx", "-y", "@modelcontextprotocol/server-everything"] ports: - containerPort: 8080 ``` `k8s/mcp-server/service.yaml` exposes it as a ClusterIP Service. The `appProtocol: agentgateway.dev/mcp` value identifies the Service as an MCP endpoint for agentgateway: ```yaml apiVersion: v1 kind: Service metadata: name: mcp-server-everything namespace: agentgateway-system labels: app: mcp-server-everything spec: selector: app: mcp-server-everything ports: - port: 80 targetPort: 8080 appProtocol: agentgateway.dev/mcp ``` ### 5.2 agentgateway Resources `k8s/agentgateway/gateway.yaml` - HTTP listener on port 80: ```yaml apiVersion: gateway.networking.k8s.io/v1 kind: Gateway metadata: name: agentgateway-proxy namespace: agentgateway-system spec: gatewayClassName: agentgateway listeners: - protocol: HTTP port: 80 name: http allowedRoutes: namespaces: from: All ``` `k8s/agentgateway/backend.yaml` - selects the MCP service by metadata label: ```yaml apiVersion: agentgateway.dev/v1alpha1 kind: AgentgatewayBackend metadata: name: mcp-backend namespace: agentgateway-system spec: mcp: targets: - name: mcp-server-everything selector: services: matchLabels: app: mcp-server-everything ``` `k8s/agentgateway/httproute.yaml` - routes traffic through the gateway to the MCP backend: ```yaml apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: mcp namespace: agentgateway-system spec: parentRefs: - name: agentgateway-proxy namespace: agentgateway-system rules: - backendRefs: - name: mcp-backend namespace: agentgateway-system group: agentgateway.dev kind: AgentgatewayBackend ``` `k8s/agentgateway/jwt-policy.yaml` - enforces JWT authentication in **Strict** mode with inline JWKS. This file is generated by the script in Step 1.3. `k8s/agentgateway/auth0-jwks-service.yaml` - scaffold for remote JWKS, not active in the current configuration. The file name uses Auth0 because this demo uses Auth0, but the concept applies to any external JWKS endpoint: ```yaml apiVersion: v1 kind: Service metadata: name: auth0-jwks namespace: agentgateway-system spec: type: ExternalName externalName: <your-tenant>.us.auth0.com ports: - port: 443 targetPort: 443 ``` Apply all manifests: ```bash kubectl apply -f k8s/mcp-server/ kubectl apply -f k8s/agentgateway/ kubectl rollout status deployment/mcp-server-everything \ -n agentgateway-system ``` --- ## Step 6 - Expose agentgateway Locally Run this in a dedicated terminal and keep it open for the duration of your session: ```bash kubectl port-forward deployment/agentgateway-proxy \ -n agentgateway-system 8080:80 ``` The MCP endpoint is now reachable locally at: ```text http://localhost:8080/mcp ``` --- ## Step 7 - Configure the MCP Host ### Claude Code `.mcp.json` configures Claude Code to launch the OAuth wrapper as the MCP server command. Fill in your provider values. Do **not** put the client secret in this file. The example variable names use `AUTH0_*` because this demo uses Auth0. ```json { "mcpServers": { "everything": { "command": "/path/to/scripts/mcp-client-auth0-wrapper.zsh", "env": { "AUTH0_DOMAIN": "<your-tenant>.us.auth0.com", "AUTH0_CLIENT_ID": "<your-client-id>", "AUTH0_AUDIENCE": "https://mcp.gateway", "AUTH0_SECRET_NAME": "<your-secret-name>", "MCP_ENDPOINT": "http://localhost:8080/mcp" } } } } ``` ### Claude Desktop, no-auth variant `config/claude_desktop_config.json` is a simpler Claude Desktop config that skips Auth0. Use this only while JWT policy is disabled or before applying the JWT policy. ```json { "mcpServers": { "everything": { "command": "npx", "args": ["-y", "supergateway", "--streamableHttp", "http://localhost:8080/mcp"] } } } ``` Copy this file to: ```text ~/Library/Application Support/Claude/claude_desktop_config.json ``` Then fully quit and relaunch Claude Desktop. --- ## How the Auth Flow Works The auth launcher uses two scripts. ### `scripts/mcp-client-auth0-wrapper.zsh` This script retrieves the OAuth client secret from macOS Keychain and then execs the next stage. ```zsh #!/bin/zsh emulate -L zsh set -euo pipefail : "${AUTH0_DOMAIN:?Missing AUTH0_DOMAIN}" : "${AUTH0_CLIENT_ID:?Missing AUTH0_CLIENT_ID}" : "${AUTH0_AUDIENCE:?Missing AUTH0_AUDIENCE}" : "${MCP_ENDPOINT:?Missing MCP_ENDPOINT}" : "${AUTH0_SECRET_NAME:?Missing AUTH0_SECRET_NAME}" AUTH0_CLIENT_SECRET="$( security find-generic-password \ -a "$USER" \ -s "$AUTH0_SECRET_NAME" \ -w )" export AUTH0_CLIENT_SECRET exec /path/to/scripts/mcp-client.sh ``` ### `scripts/mcp-client.sh` This script exchanges the client credentials for a short-lived JWT access token, then starts `supergateway`. ```bash #!/bin/bash set -euo pipefail TOKEN="$(curl -sf -X POST "https://${AUTH0_DOMAIN}/oauth/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials&client_id=${AUTH0_CLIENT_ID}&client_secret=${AUTH0_CLIENT_SECRET}&audience=${AUTH0_AUDIENCE}" \ | jq -r .access_token)" exec npx -y supergateway \ --streamableHttp "${MCP_ENDPOINT}" \ --header "Authorization: Bearer ${TOKEN}" ``` > The token is acquired when the MCP process starts. For long-running sessions, add token renewal logic or restart the MCP process when the token expires. --- ## Step 8 - Validate ### 8.1 Confirm a valid token is accepted Fetch a token from the authorization server and use it in a request. This example uses Auth0: ```bash TOKEN="$(curl -sf -X POST "https://<your-domain>/oauth/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials&client_id=<your-client-id>&client_secret=<your-client-secret>&audience=https://mcp.gateway" \ | jq -r .access_token)" curl -s -X POST http://localhost:8080/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Authorization: Bearer ${TOKEN}" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' ``` Expected result: - HTTP `200` - an `Mcp-Session-Id` response header - an MCP initialize result - no `authentication failure` in the body ### 8.2 Confirm a bad token is rejected Malformed JWT: ```bash curl -s -X POST http://localhost:8080/mcp \ -H "Content-Type: application/json" \ -H "Authorization: Bearer invalid.jwt.token" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"echo","arguments":{"message":"test"}}}' ``` Expected: ```text authentication failure: the token header is malformed ``` Structurally valid JWT with unknown key ID: ```bash HEADER="$(echo -n '{"alg":"RS256","typ":"JWT","kid":"fake-key-id"}' | base64 | tr '+/' '-_' | tr -d '=')" PAYLOAD="$(echo -n '{"sub":"test","iss":"https://<your-domain>/","aud":"https://mcp.gateway","exp":9999999999}' | base64 | tr '+/' '-_' | tr -d '=')" SIG="ZmFrZXNpZ25hdHVyZQ" curl -s -X POST http://localhost:8080/mcp \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${HEADER}.${PAYLOAD}.${SIG}" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"echo","arguments":{"message":"test"}}}' ``` Expected: ```text authentication failure: token uses the unknown key "fake-key-id" ``` ### 8.3 Automated JWT policy tests `scripts/security_testing/Test-JwtPolicy.ps1` exercises the gateway's JWT enforcement with a structured test matrix. It requires the `PSJsonWebToken` module and a running agentgateway reachable at `http://localhost:8080`. ```powershell Install-Module PSJsonWebToken ``` Set environment variables for your Auth0 tenant (or pass them as parameters): ```powershell $env:AUTH0_DOMAIN = '<your-domain>' $env:AUTH0_CLIENT_ID = '<your-client-id>' $env:AUTH0_CLIENT_SECRET = '<your-client-secret>' $env:AUTH0_AUDIENCE = 'https://mcp.gateway' ``` Run the suite: ```powershell ./scripts/security_testing/Test-JwtPolicy.ps1 ``` Test matrix: | # | Scenario | Expected | |---|--------------------------------|----------| | 1 | No Authorization header | 401 | | 2 | Garbage token | 401 | | 3 | HS256 token (algorithm confusion) | 401 | | 4 | Expired JWT | 401 | | 5 | Wrong audience | 401 | | 6 | Wrong issuer | 401 | | 7 | Valid Auth0 JWT | 2xx | The script prints colored pass/fail output for each case and exits with a non-zero code if any test fails, making it suitable for use in a CI pipeline. If `AUTH0_DOMAIN`, `AUTH0_CLIENT_ID`, or `AUTH0_CLIENT_SECRET` are not set, the live-token tests (cases 1–6 still run using locally constructed tokens; case 7 is skipped). --- ## Security Notes This repo demonstrates a useful gateway pattern, but there are important boundaries: - **Client credentials is application identity.** The gateway authenticates the MCP host/application, not the individual user. - **The client secret still exists at runtime.** Keychain keeps it out of `.mcp.json` and out of the repo, but the wrapper exports it to the child process so `mcp-client.sh` can request a token. - **The JWT should be short-lived.** Do not rely on a long-lived bearer token. - **Validate audience and issuer.** The token should be issued by the expected authorization server and intended for the MCP gateway audience. - **Do not expose this over plain HTTP in production.** This demo uses local `kubectl port-forward` and `localhost`. - **Add policy for real use.** JWT validation is only the first layer. Real deployments should also consider per-client authorization, per-tool authorization, logging, rate limiting, egress controls, and data handling policies. --- ## Troubleshooting ### `mcp: no backends configured` The `AgentgatewayBackend` selector matches Service **metadata labels**, not just `spec.selector`. Verify the Service has the expected label: ```bash kubectl get svc mcp-server-everything \ -n agentgateway-system \ --show-labels ``` ### MCP server pod not starting ```bash kubectl describe pod -l app=mcp-server-everything \ -n agentgateway-system kubectl logs deployment/mcp-server-everything \ -n agentgateway-system ``` ### Keychain secret not found ```bash security find-generic-password \ -a "$USER" \ -s <your-secret-name> \ -w ``` If it returns nothing, repeat Step 2. ### Port already in use ```bash lsof -ti:8080 | xargs kill ``` ### Teardown ```bash helm uninstall agentgateway agentgateway-crds \ -n agentgateway-system kubectl delete namespace agentgateway-system minikube delete ```

mcp-agentgateway-jwt-auth

内容

MCP 配置

连接信息

猜你喜欢

mcp-agentgateway-jwt-auth

微信扫一扫分享

需要认证

内容

MCP 配置

连接信息

猜你喜欢