[Automated] Draft docs (agentgateway): allow mcp auth with jwt validation

[github-actions]

agentgateway/agentgateway#3936 — allow mcp auth with jwt validation

Docs versions: standalone/main, kubernetes/main

What changes for users: MCP authentication can now run after route-level JWT authentication when preserveToken: true keeps the token available. In strict mode, MCP authentication rejects the request only when a previous Gateway or Route JWT policy removed the token; in permissive mode, that missing-token case is skipped.

What the docs now say: The Kubernetes JWT setup page and the standalone JWT authentication page now say that preserveToken also lets MCP authentication validate the same token after route-level JWT authentication.

Not verified: No cluster or standalone binary run; the configuration is unrun.

How agentgateway-3936 was drafted, and what was not verified

• Code PR: allow mcp auth with jwt validation agentgateway#3936
• Code issue: none linked
• Product: agentgateway (upstream) → agentgateway/website
• Docs version: standalone/main and kubernetes/main
• Category: scoped-edit / pr

Plan, and what changed it

• Planned: Document the preserveToken requirement where the JWT pages already describe downstream policies that read a validated token.
• Learned: The dossier diff and changed-functions.md show the behavior is specifically MCP authentication after route-level JWT validation, while the target JWT pages already own preserveToken.
• Did: Added the MCP authentication case to the Kubernetes and standalone JWT pages, with the Kubernetes shared asset gated to main-only docs.

Why a documentation change is necessary

The pull request changes apply_token_validation so MCP authentication no longer rejects every request that already has JWT claims. It rejects only when a previous JWT policy validated and removed the token, and the tests show preserveToken: true lets strict MCP authentication validate a token whose audiences include both the route JWT audience and the MCP audience. The JWT docs already tell readers to set preserveToken for token exchange, but they did not name MCP authentication as another policy that reads the same token from the request.

What changed on disk

• assets/agw-docs/pages/security/jwt-setup.md — Adds the MCP authentication use case to the preserveToken field row for Kubernetes main docs, behind a main-only version gate.
• content/docs/standalone/main/documentation/configuration/security/jwt-authn.md — Adds the same MCP authentication use case to the standalone main JWT authentication page.

How to verify this change

1. Configure a standalone MCP route with both routes[].policies.jwtAuth.preserveToken: true and routes[].policies.mcpAuthentication on the same route.
2. Send an MCP initialize request with a valid bearer token whose aud claim includes both the route JWT audience and the MCP authentication audience. The request returns 200.
3. Remove preserveToken from the route JWT policy and repeat the request. In strict mode, the request returns 401 with the message MCP backend authentication configured but the token was removed by a Gateway or Route level JWT policy; set preserveToken on that policy.

What was not verified

The configuration was not applied to a cluster, and no standalone agentgateway binary was run. No example output blocks were changed.

How the pages were chosen (triage report)

Draft a documentation change

agentgateway/agentgateway#3936 — allow mcp auth with jwt validation

• Product: agentgateway (upstream) → agentgateway/website
• Docs version: standalone/main, kubernetes/main
• Summary (read from the body): When preserveToken: true we can still run MCP backend authentication. Only reject when the token is not available.
• Not tested: no cluster was available, so every command in this diff is unrun

Release notes

This pull request also adds its release-note entries:

• content/docs/standalone/main/release-notes/release-notes.md: allow mcp auth with jwt validation (fix, under MCP)

Release notes kept out of a tree. Check that each change really does not reach the trees named here:

• allow mcp auth with jwt validation agentgateway#3936: not placed for kubernetes/main, because the draft edited no page there. If the change also reaches that tree, add the note there.

Draft branch: pr-tracker-draft-agentgateway-3936

---

Important

The test suite has not run on this pull request. It was opened by github-actions[bot], and GitHub does not start workflows for pull requests opened with the repository's own token. Doc tests, link checking and the static checks are held as action_required until somebody presses Approve and run on the Checks tab. Cloudflare Pages and DCO are GitHub Apps rather than Actions, so those two do run on their own.

Please approve the checks before reviewing the content: an absence of failures here means the tests have not run, not that they passed.

[cloudflare-workers-and-pages]

Deploying agentproxy with    Cloudflare Pages

Latest commit:	fdb0598
Status:	✅  Deploy successful!
Preview URL:	https://e17213c9.agentproxy.pages.dev
Branch Preview URL:	https://pr-tracker-draft-agentgatewa-wqg9.agentproxy.pages.dev

View logs