Align MCP OAuth authorization with latest MCP spec

[Agent-Hellboy]

Summary

MCP Runtime's gateway OAuth support is partially aligned with the latest MCP Authorization spec, but there are gaps to close for protected HTTP MCP servers.

Spec reference: https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization

Current state

The platform already supports:

• MCPServer.spec.auth.mode values: none, header, and oauth.
• OAuth bearer JWT validation in services/mcp-proxy for signature, issuer, allowed algs, and optional audience.
• Protected Resource Metadata at /.well-known/oauth-protected-resource... with authorization_servers.
• 401 for missing/invalid bearer tokens and 403 for local policy denials.
• Local governance extensions through grants, sessions, trust levels, expiry, revocation, and policy versions.

Relevant files:

• api/v1alpha1/mcpserver_types.go
• pkg/policy/types.go
• internal/operator/controller.go
• services/mcp-proxy/main.go

Gaps to close

1. Require resource/audience binding in OAuth mode

The MCP spec requires protected MCP servers to validate that access tokens were issued specifically for that MCP server/resource. Today the proxy only validates aud when spec.auth.audience is configured.

Acceptance criteria:

• Define the canonical MCP resource URI for a proxied server, including path-based endpoints such as https://mcp.example.com/<server>/mcp.
• Require audience/resource validation for auth.mode: oauth, or fail closed when no audience/resource is configured or derivable.
• Add tests for valid audience, missing audience, wrong audience, and path-based server URI cases.

2. Prevent bearer token passthrough by default

The latest MCP spec explicitly forbids MCP servers from passing through the client bearer token to upstream APIs. Today the proxy can forward inbound Authorization unless explicitly removed/replaced, and UpstreamTokenHeader can be set to forward the inbound token.

Acceptance criteria:

• Strip inbound OAuth token headers before forwarding to the upstream MCP server unless there is an explicit, spec-safe token exchange / upstream-token mechanism.
• Do not reuse the client's MCP bearer token as an upstream API token.
• Add tests proving inbound Authorization is removed in OAuth mode.

3. Add scope-aware challenges and insufficient-scope responses

The spec recommends WWW-Authenticate scope hints on auth challenges and error="insufficient_scope" with required scopes for runtime 403 responses.

Acceptance criteria:

• Extend policy/config to express MCP/OAuth scopes, or map local tool/trust denials to stable scope names.
• Include scope in relevant WWW-Authenticate challenges where known.
• For insufficient permissions, return 403 with a Bearer challenge containing error="insufficient_scope", resource_metadata, and required scope when available.
• Add tests for missing token, invalid token, and insufficient-scope/tool-denied cases.

4. Align authorization server metadata discovery ordering

The latest MCP spec requires a specific discovery order for OAuth Authorization Server Metadata and OIDC Discovery, especially for issuer URLs with path components.

Acceptance criteria:

• Adjust authServerMetadataCandidates to match the latest spec ordering.
• Add table-driven tests for issuer URLs with and without path components.

5. Clarify client registration support

The latest spec prefers OAuth Client ID Metadata Documents and allows Dynamic Client Registration as a fallback. MCP Runtime currently integrates with external IdPs/resource-server behavior; it does not appear to implement an MCP authorization server.

Acceptance criteria:

• Document what MCP Runtime supports today: resource server validation with external authorization servers.
• Explicitly state whether Client ID Metadata Documents / Dynamic Client Registration are out of scope, planned, or delegated to the external authorization server.

Notes

This issue is about MCP spec compliance for HTTP OAuth-protected MCP servers. The existing grant/session/trust model should remain as MCP Runtime's platform governance layer on top of spec-compliant transport authorization.