feat: Implement OAuth 2.1 authentication for MCP server HTTP transports

[mgmonteleone]

Overview

The MCP server currently uses simple Bearer token authentication for HTTP transports (streamable-http, sse). The MCP specification recommends OAuth 2.1 for multi-tenant and public deployments. This issue tracks implementing proper OAuth 2.1 support.

Background

• Phase 4 (PR Phase 4: Production Transports & Security #125) originally planned OAuth 2.1 but shipped with Bearer token auth instead
• PR feat: Implement Cloud Run deployment pipeline with token-based MCP auth #135 implements Cloud Run deployment with token-based auth via Google Secret Manager
• Current auth: BearerTokenMiddleware in src/devrev_mcp/middleware/auth.py validates a single static token
• The MCP spec (2024-11-05+) defines an OAuth 2.1 authorization flow for HTTP transports

Current Auth Stack

Transport	Auth Method	Status
stdio	None (local)	✅ Implemented
streamable-http	Bearer token	✅ Implemented (Phase 4)
sse	Bearer token	✅ Implemented (Phase 4)
streamable-http	OAuth 2.1	❌ Not implemented
sse	OAuth 2.1	❌ Not implemented

Requirements

Core OAuth 2.1 Flow

• Implement OAuth 2.1 Authorization Server metadata discovery (RFC 8414)
• Support Authorization Code Grant with PKCE (RFC 7636)
• Token endpoint for access token issuance and refresh
• Token introspection/validation middleware
• Proper error responses per OAuth 2.1 spec (RFC 6749 Section 5.2)

MCP-Specific Requirements

• Implement MCP authorization flow as defined in the MCP spec
• Support /.well-known/oauth-authorization-server metadata endpoint
• Dynamic client registration (RFC 7591) — optional but recommended
• Scope-based access control for MCP tools/resources
• Session binding between OAuth tokens and MCP sessions

Configuration

• Add OAuth config fields to MCPServerConfig (issuer, client credentials, JWKS URI, etc.)
• Support both standalone OAuth server and external IdP integration
• Backward-compatible — existing Bearer token auth must continue to work
• Environment variable configuration with MCP_OAUTH_* prefix

Security

• PKCE required (no implicit/client-credentials for public clients)
• Token expiration and refresh token rotation
• Secure token storage recommendations in docs
• HTTPS enforcement for OAuth endpoints
• CORS configuration for OAuth endpoints

Testing

• Unit tests for OAuth middleware
• Unit tests for token validation
• Integration tests with mock OAuth server
• E2E tests with real OAuth flow
• Test backward compatibility with existing Bearer token auth

Documentation

• OAuth setup guide in deploy/README.md
• Client configuration examples (Claude Desktop, Augment, etc.)
• External IdP integration guide (Google, Auth0, etc.)
• Security best practices

Design Considerations

1. Backward Compatibility: Must not break existing Bearer token auth. OAuth should be opt-in via config.
2. External IdP vs Built-in: Consider supporting delegation to external OAuth providers (Google Cloud Identity, Auth0, Okta) rather than implementing a full OAuth server.
3. MCP Spec Compliance: Follow the MCP authorization spec exactly for interoperability with all MCP clients.
4. Scope Mapping: Map OAuth scopes to MCP tool categories (e.g., mcp:tools:read, mcp:tools:write, mcp:resources:read).

Related

• PR Phase 4: Production Transports & Security #125 — Phase 4: Production Transports & Security (Bearer token auth)
• PR feat: Implement Cloud Run deployment pipeline with token-based MCP auth #135 — Cloud Run deployment with token-based auth
• PR Fix: HTTP Middleware Registration + E2E Testing #128 — HTTP middleware registration fix
• MCP Authorization Spec

Acceptance Criteria

1. MCP clients can authenticate via OAuth 2.1 Authorization Code + PKCE flow
2. Existing Bearer token auth continues to work unchanged
3. OAuth is opt-in via configuration (MCP_OAUTH_ENABLED=true)
4. All tests pass (unit, integration, E2E)
5. Documentation covers setup, configuration, and security
6. Cloud Run deployment docs updated with OAuth setup instructions

[mgmonteleone]

Status Update: Deferred in favor of per-user DevRev PAT auth

After analysis, we've determined that the immediate critical requirement — per-user attribution of all DevRev API actions — can be met with a significantly simpler approach than full OAuth 2.1.

What we're implementing instead

See #145 — Per-user DevRev PAT authentication for MCP HTTP transports. The approach:

1. Each user configures their own DevRev Personal Access Token as the Authorization: Bearer header in their MCP client config
2. A new DevRevPATAuthMiddleware validates the PAT against the DevRev API and extracts user identity
3. A per-request AsyncDevRevClient is created using the user's own PAT
4. All DevRev API calls are attributed to the individual user
5. Access is restricted to @augmentcode.com email domains

Why this is sufficient for now

• ✅ Per-user attribution — each user's actions are traceable in DevRev
• ✅ Domain restriction — only @augmentcode.com users can access
• ✅ No new infrastructure — no OAuth provider, no Firestore, no session management
• ✅ Simple client config — users just put their DevRev PAT in the bearer token field
• ✅ Secure — PATs travel over HTTPS (Cloud Run enforces TLS), no server-side token storage

When would we revisit OAuth 2.1?

This issue remains open for future consideration if any of these needs arise:

• Multi-tenant access (non-DevRev users need access)
• Third-party integrations that can't use DevRev PATs
• Fine-grained scope-based access control (e.g., read-only vs. read-write per tool category)
• SSO/SAML integration requirements
• Compliance requirements mandating OAuth specifically

For now, this issue is deprioritized — not cancelled.