Document vMCP embedded authorization server and upstream token injection

[jhrozek]

Summary

Document the new vMCP embedded authorization server and upstream token injection features introduced by the following RFCs:

• RFC-0052: Multi-upstream IDP support in the embedded auth server
• RFC-0053: Embedded auth server in vMCP
• RFC-0054: upstream_inject outgoing auth strategy

What needs documenting

Three interlocking capabilities that enable vMCP to authenticate users through multiple upstream identity providers and inject their tokens into backend requests:

1. Embedded authorization server on VirtualMCPServer — authServerConfig inline field that runs an OAuth authorization server within the vMCP process, supporting multiple upstream providers with sequential authorization chaining and DCR.

2. upstream_inject outgoing auth strategy — New MCPExternalAuthConfig type (upstreamInject) that injects stored upstream provider tokens into outgoing backend requests.

3. subjectProviderName on token exchange — New field on tokenExchange configs that selects which upstream provider's token to use as the subject token for RFC 8693 exchange, enabling hybrid deployments where some backends use direct injection and others use exchanged tokens.

Documentation plan

New content

• docs/toolhive/guides-vmcp/authentication.mdx — Extend with:
  • "Upstream token injection" section (MCPExternalAuthConfig with upstreamInject type)
  • "Token exchange with upstream tokens" section (subjectProviderName)
  • "Embedded authorization server" section (how it works, differences from MCPServer, config, incoming auth wiring, session storage, complete example)

Updates to existing content

• docs/toolhive/concepts/vmcp.mdx — Mention embedded auth server capability under "Authentication boundary separation"; fix "four key benefits" → "five"
• docs/toolhive/concepts/backend-auth.mdx — Update "single upstream provider" claim to clarify it's MCPServer-only; remove outdated "chained authentication not yet supported" admonition; add cross-reference to vMCP guide
• docs/toolhive/guides-k8s/auth-k8s.mdx — Add cross-reference to vMCP embedded auth server in related information

Out of scope

• CRD reference (reference/crd-spec.md) — auto-generated, will update when CRDs are regenerated
• Partials refactoring to deduplicate shared content between K8s and vMCP auth guides (separate task)

Implementation status

• RFC-0052 (multi-upstream): fully merged
• RFC-0053 (embedded AS in vMCP): mostly merged, PR feat: add authorizationEndpointBaseUrl override to embedded auth server toolhive#4396 merged today
• RFC-0054 (upstream_inject): PRs Implement upstream_inject strategy and SubjectProviderName toolhive#4390, Add CRD type and converter for upstream_inject strategy toolhive#4391, Wire UpstreamTokenReader into vMCP incoming auth middleware toolhive#4394 approved/open

Documentation should land after all PRs are merged.