[github-actions]

agentgateway/agentgateway#4006 — mcp: Return 401 for expired OAuth subject tokens

Docs versions: standalone/main, kubernetes/main

No code-path rule covers 1 touched file(s). The planner could route these only by identifier search, so the candidate pages may miss what they changed, including in the other mode:

• crates/agentgateway/src/proxy/mod.rs

What changes for users: MCP requests with an expired JWT-shaped OAuth subject token now receive 401 with invalid_token before token exchange calls the token endpoint. MCP fail-open routing still skips unavailable targets, but bearer-token rejections reach the client so the client can refresh and retry.

What the docs now say: The standalone MCP authentication page, the Kubernetes MCP auth overview, the MCP token-exchange guide, the standard token-exchange guides, and the MCP multiplexing guide now describe the expired-token rejection and the fail-open exception for bearer-token rejections.

Not verified: No cluster or standalone proxy was run; the configuration and behavior are unrun.

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

• Code PR: mcp: Return 401 for expired OAuth subject tokens agentgateway#4006
• Code issue: none linked
• Product: agentgateway (upstream) → agentgateway/website
• Docs version: standalone/main and kubernetes/main
• Category: scoped-edit / pr
• Possibly incomplete: MCP target with oauthTokenExchange: an expired client JWT is answered with 500 for ~60 s instead of 401, so clients never refresh agentgateway#3907 was not in this run; the planner says #4006 names it as part of the same feature.

Plan, and what changed it

• Planned: Add the expired subject-token and fail-open behavior to the pages that already document MCP authentication, MCP token exchange, and MCP multiplexing.
• Learned: The Kubernetes MCP auth and multiplexing pages are wrappers around shared assets/agw-docs files, and version-gates.md requires main-only behavior in shared assets to be gated.
• Did: Updated the standalone main page directly, updated shared Kubernetes assets with gates that exclude older versions, and wrote an MCP release-note bullet.

Why a documentation change is necessary

The pull request changes observable MCP authentication behavior: expired JWT-shaped subject tokens are rejected locally with 401 and invalid_token, and MCP fail-open routing no longer hides bearer-token rejections. The existing MCP auth pages described connect-time authentication but did not say what a client sees when a later bearer token expires. The existing token-exchange pages said the exchange does not validate the incoming token before the token endpoint call; that remains true for trust, but the dossier diff adds a local expiry check that readers need to know about.

What changed on disk

• assets/agw-docs/pages/agentgateway/mcp/mcp-auth-about.md — Adds the gated Kubernetes MCP auth behavior for expired bearer tokens.
• assets/agw-docs/pages/agentgateway/mcp/multiplex.md — Adds the gated fail-open exception for bearer-token rejections.
• assets/agw-docs/pages/security/backend-authn-te-mcp.md — Adds the gated MCP token-exchange behavior for expired JWT-shaped subject tokens.
• assets/agw-docs/pages/security/backend-authn-te-standard.md — Adds the gated Kubernetes standard token-exchange expiry check.
• assets/agw-docs/pages/security/backend-authn-te-standard-standalone.md — Adds the gated standalone standard token-exchange expiry check.
• content/docs/standalone/main/documentation/configuration/security/mcp-authn.md — Adds the standalone main MCP auth behavior for expired bearer tokens.

How to verify this change

1. In standalone mode, follow the MCP authentication page with a token-exchange policy that reads the bearer token as the subject token. Send an MCP request with an expired JWT-shaped bearer token; the response should be 401 and include invalid_token in the MCP authentication challenge.
2. In Kubernetes mode, follow the Token exchange for MCP servers guide. Reuse an expired INBOUND_TOKEN for the MCP tool call; the response should be 401 before the token endpoint receives a new exchange request.
3. For a multiplexed MCP backend with failureMode: FailOpen, make one target return a bearer-token rejection. The request should return the 401 challenge instead of skipping that target as unavailable.

What was not verified

• The configuration was not applied to a cluster or run through a standalone proxy, so every behavior described in this diff is unrun.
• Hugo was not run; internal links are unchecked.
• The dossier says eight changed functions were omitted from changed-functions.md; the docs claims are based on the visible diff, tests, and listed changed functions.

How the pages were chosen (triage report)

Feature clusters

These clusters look incomplete. Each names a pull request this run never saw, so documenting the cluster as it stands may describe half a feature — the classic failure is a guide telling a reader to set a field that a later change gave a default. Read the absent pull request before drafting:

Cluster	Missing	What it is	Why it matters
c3	agentgateway/agentgateway#3907	not looked up	agentgateway/agentgateway#4006 names it as part of the same feature

Draft a documentation change

agentgateway/agentgateway#4006 — mcp: Return 401 for expired OAuth subject tokens

• Product: agentgateway (upstream) → agentgateway/website
• Docs version: standalone/main, kubernetes/main
• Summary (read from the body): Reject verified expired subject tokens before token exchange. Preserve MCP discovery challenges and propagate authentication failures through fail-open routing and SSE transports so clients can refresh and retry.
• Not tested: no cluster was available, so every command in this diff is unrun
• No rule covers 1 touched file(s). The candidate pages below come from the files that DID match a rule, so they may scope this narrower than the change is. Read these before deciding the change is only about the pages listed:
  • crates/agentgateway/src/proxy/mod.rs

Release notes

This pull request also adds its release-note entries:

• content/docs/kubernetes/main/release-notes/release-notes.md: mcp: Return 401 for expired OAuth subject tokens (fix, under MCP, in a new 1.8 section)
• content/docs/standalone/main/release-notes/release-notes.md: mcp: Return 401 for expired OAuth subject tokens (fix, under MCP, in a new 1.8 section)

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

[cloudflare-workers-and-pages]

Deploying agentproxy with    Cloudflare Pages

Latest commit:	f9ef720
Status:	✅  Deploy successful!
Preview URL:	https://4a84dea8.agentproxy.pages.dev
Branch Preview URL:	https://pr-tracker-draft-agentgatewa-zhfy.agentproxy.pages.dev

View logs

[kristin-kronstain-brown]

Moved this PR's release-notes entry to the combined release-notes PR, #1482, so the draft PRs stop conflicting on the release-notes pages. Review or change the entry there.