Add OAuth 2.1 authentication support with external provider integration

[r33drichards]

Summary

This PR adds comprehensive OAuth 2.1 authentication support to the MCP server, enabling secure token-based access control for HTTP/SSE transports. The implementation supports both a built-in OAuth provider and delegation to external OIDC providers (e.g., Keycloak).

Key Changes

• New OAuth module (server/src/oauth.rs): Complete OAuth 2.1 implementation including:

  • Authorization Code flow with PKCE support (S256 and plain methods)
  • Dynamic Client Registration (RFC 7591)
  • Token introspection for external OIDC providers
  • Bearer token validation middleware
  • Metadata discovery endpoint (.well-known/oauth-authorization-server)

• Dual-mode operation:

  • Built-in mode: Server acts as OAuth provider with local client/token storage
  • External provider mode: Server delegates to external OIDC provider (e.g., Keycloak) and validates tokens via introspection endpoint

• CLI options for OAuth configuration:

  • --oauth: Enable OAuth authentication
  • --oauth-issuer: Set the issuer URL (defaults to server's base URL)
  • --oauth-provider-url: External OIDC provider URL
  • --oauth-client-id / --oauth-client-secret: Credentials for provider introspection

• Transport integration: Updated HTTP and SSE transport initialization to apply token validation middleware when OAuth is enabled

• Testing infrastructure:

  • docker-compose.oauth.yml: Pre-configured stack with Keycloak as external provider
  • keycloak/realm.json: Pre-configured realm with test users and clients
  • OAUTH_TESTING.md: Comprehensive testing guide with curl examples and troubleshooting

Implementation Details

• Token validation uses RFC 7662 token introspection for external providers
• PKCE verification implemented with SHA256 hashing and base64url encoding
• Authorization codes and tokens are stored in-memory with Arc for thread-safe access
• Metadata endpoint intelligently returns provider's endpoints in external mode, server's endpoints in built-in mode
• All OAuth endpoints return proper error responses per OAuth 2.0 spec
• Bearer token extraction and validation happens in middleware, protecting all downstream routes

https://claude.ai/code/session_01EzekKCTDGrff31LeVZZpyu

[github-actions]

MCP-V8 Load Test Benchmark Report

Comparison of single-node vs 3-node cluster at various request rates.

Results

Topology	Target Rate	Actual Iter/s	HTTP Req/s	Exec Avg (ms)	Exec p95 (ms)	Exec p99 (ms)	Success %	Dropped	Max VUs
cluster-stateful	100/s	99.6	332.6	68.46	153.24	254.43	100%	15	25
cluster-stateful	200/s	119.5	3831.8	1543.81	4688.06	5060.46	99.1%	4293	200
cluster-stateless	1000/s	281.1	679.7	3288.83	10585.61	14442.5	92.3%	41568	1000
cluster-stateless	100/s	99.9	299.8	53.33	55.97	58.44	100%	0	10
cluster-stateless	200/s	199.7	599.7	55.47	60.16	69.32	100%	6	25
cluster-stateless	500/s	383.1	1059.4	825.61	3992.71	7728.51	99.8%	6191	500
single-stateful	100/s	46.4	1967.3	2050.48	2388.37	2539.59	100%	3113	100
single-stateful	200/s	45.1	3785.3	4182.12	4939.84	5075.88	98.5%	9066	200
single-stateless	1000/s	127.4	246.3	7374.73	11571.68	14983.17	59.8%	51647	1000
single-stateless	100/s	99.9	299.8	53.65	56.77	59.7	100%	0	10
single-stateless	200/s	184	502.4	356.03	1535.73	3046.97	100%	831	200
single-stateless	500/s	121.3	320.1	3977.74	9022.89	11510.88	99.2%	22539	500

P95 Latency

Topology	Rate	P95 (ms)
cluster-stateful	100/s	153.24	████████████████
cluster-stateful	200/s	4688.06	███████████████████████████
cluster-stateless	100/s	55.97	█████████████
cluster-stateless	200/s	60.16	█████████████
cluster-stateless	500/s	3992.71	███████████████████████████
cluster-stateless	1000/s	10585.61	██████████████████████████████
single-stateful	100/s	2388.37	█████████████████████████
single-stateful	200/s	4939.84	███████████████████████████
single-stateless	100/s	56.77	█████████████
single-stateless	200/s	1535.73	████████████████████████
single-stateless	500/s	9022.89	█████████████████████████████
single-stateless	1000/s	11571.68	██████████████████████████████

Notes

• Target Rate: The configured constant-arrival-rate (requests/second k6 attempts)
• Actual Iter/s: Achieved iterations per second (each iteration = 1 POST /api/exec)
• HTTP Req/s: Total HTTP requests per second (1 per iteration)
• Dropped: Iterations k6 couldn't schedule because VUs were exhausted (indicates server saturation)
• Topology: single = 1 MCP-V8 node; cluster = 3 MCP-V8 nodes with Raft