MCP Authentication

[npolshakova]

Description

Motivation:
Allows users to configure MCP authentication for MCP backends.

What changed:
Requires these PRs to go in first :)

• Support for Remote Jwks in JwtAuthentication Policies #12850 (depends on remote fetch for mcp IDPs)
• api: Add AgentgatewayBackend #12830 (needs dataplane changes from this pr for AI backend translation changes)
• feat: Support MCP Authn when configured by xDS agentgateway/agentgateway#637 (currently pinned to local version based on this branch)

Fixes #12469

Change Type

/kind feature

Changelog

Added support for MCP authentication for agentgateway.

Additional Notes

For testing MCP Authentication with keycloak, apply the remote-authn-keycloak.yaml, common.yaml and keycloak.yaml manifests along with the curl_pod.yaml from the e2e test setup.

1. Send a request without authorization header:

curl -v -X POST http://gw.default.svc.cluster.local:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json,text/event-stream" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "fetch",
      "arguments": { "url": "http://google.com" }
    }
  }'

2. You should get a 401 Unauthorized response:

< HTTP/1.1 401 Unauthorized
< www-authenticate: Bearer resource_metadata="http://mcp-website-fetcher.default.svc.cluster.local/.well-known/oauth-protected-resource/mcp"
< content-type: application/json
< content-length: 65
< date: Thu, 20 Nov 2025 14:32:26 GMT
< 
* Connection #0 to host localhost left intact
{"error":"unauthorized","error_description":"JWT token required"}%

3. From the curl pod you should be able to get a token from keycloak under access_token and save it as TOKEN:

curl -s -X POST "http://keycloak.default:7080/realms/mcp/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=mcp_proxy" \
  -d "client_secret=supersecret"

4. Then use the token to make the request:

curl -v -X POST http://gw.default.svc.cluster.local:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json,text/event-stream" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "fetch",
      "arguments": { "url": "http://google.com" }
    }
  }'

You should no longer see the 401 error!

You can also test this with the MCP inspector:

1. Run npx modelcontextprotocol/inspector#0.16.2
2. Open the inspector UI
3. Attempt to connect to the port-forwarded gateway (http://localhost:8080/) without the token using Streamable HTTP
4. Set the TOKEN under the API Token Authentication field, then click Connect
5. Go to the tools tab and test the fetch tool with a URL of your choice

Example without the token:

Example with token:

Follow ups:

• Add mode configuration to support non-optional jwt modes

[Copilot]

Pull request overview

This PR adds MCP (Model Context Protocol) authentication support to the agentgateway, enabling JWT-based authentication for MCP backends with support for Auth0 and Keycloak identity providers.

Key changes:

• Added MCP authentication policy configuration with JWKS validation
• Implemented Auth0 mock server for e2e testing
• Extended JWKS store controller to handle MCP authentication JWKS sources

Reviewed changes

Copilot reviewed 26 out of 27 changed files in this pull request and generated 14 comments.

Show a summary per file

File	Description
api/v1alpha1/agentgateway_policy_types.go	Added MCPAuthentication type with issuer, audiences, JWKS, and IDP configuration
api/v1alpha1/zz_generated.deepcopy.go	Generated deep copy methods for new authentication types
pkg/agentgateway/plugins/backend_policies.go	Implemented translateBackendMCPAuthentication to convert policy to agentgateway format
internal/kgateway/agentjwksstore/jwks_store_controller.go	Extended to fetch JWKS from both AgentgatewayPolicy and AgentgatewayBackend MCP auth configs
install/helm/kgateway-crds/templates/*.yaml	Updated CRDs with MCP authentication schema
test/e2e/features/agentgateway/mcp/*	Added e2e tests for MCP authentication with Auth0 mock
hack/dummy-auth0/*	New Python-based Auth0 mock server for testing OAuth flows
go.mod	Uses local replace directive for agentgateway dependency
Makefile	Added build targets for dummy-auth0 Docker image

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[yuval-k]

why do we need to know the IDP type? i.e. why isn't the issuer enough?

[npolshakova]

We use the idp to determine the path type: https://github.com/agentgateway/agentgateway/blob/a479200e2076bbaaa7321b2d439b5c19c9d44030/crates/agentgateway/src/types/agent.rs#L1331

[dmitri-d]

not related to the PR, is the above a constraint in our implementation, or is it coming from a spec? The spec i was able to find (https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization#third-party-authorization-flow) is pretty minimal when it comes to third-party auth providers.

[npolshakova]

Our implementation- the idp and issuers are both determining the path in the line I sent earlier.

[dmitri-d]

I think we should look more closely at intoducing a jwks backend for AgentgatewayPolicy (see notes in #13014 for examples), as it would unify tls/traffic config UX and handling for fetching of remote jwks.

[howardjohn]

should not be map[string]string but rather map[string]JsonValue. I think the appropriate way to represent this is map[string]apiextensionsv1.JSON in kubebuilder but not 100% sure it works inside a map. You can see similar in FieldDefault

[npolshakova]

It looks like ResourceMetadata map[string]apiextensionsv1.JSON worked with kubebuilder 🎉

[howardjohn]

nit: provider or identityProvider I think may be more fitting

[npolshakova]

I'll use provider since it's already under the mcp.authentication fields. I think identityProvider is a little too long

[howardjohn]

nit: would be great to not have so many different mocks. can we just merge this in with the Golang mock IDP?

Have a separate image, especially a python one, is going to bloat our CI times

[npolshakova]

Ideally, yes- I think @shashankram is also looking at adding a provider for e2e tests on the envoy side. The current golang mock idp we're using for the jwt tests is pretty jwt specific (it just provides the different jwks to fetch, doesn't have the paths we need to test the mcp auth flow integration). I think we should discuss offline and consolitdate into having one e2e idp provider that ideally works for all these scenarios.

[dmitri-d]

I did a minimal thing just to support remote jwks e2e tests; we could extend the fake idp, or even have a real idp with fake data (like using zitadel + preset accounts and jwks; not sure re: jwts, those may need to be generated).

[howardjohn]

This needs a proto change, but we need a way to represent "no provider".

Provider means "this provider is no implementing the proper RFCs and needs workarounds" so ideally a user doesn't need one at all. And we should not default to keycloak

[npolshakova]

It currently defaults to auth0, but agree- it would be ideal to not require a provider. Will create a follow up for this to make the dataplane change along with the mode configuration to support non-optional jwt modes

[howardjohn]

if we do my commet on the API we don't need this or the json-in-string from users