Add MCP OAuth flow support

[heskew]

Add MCP OAuth flow support

Adds Model Context Protocol authorization-server support to @harperfast/oauth so any Harper app already using the plugin for human OAuth (GitHub, Google, Azure, Auth0, custom OIDC) can also act as an OAuth source for MCP clients (Claude Desktop, Cursor, mcp-remote). The MCP flow bridges to the existing upstream-IdP dance rather than reimplementing it; onLogin and the rest of the lifecycle hooks fire unchanged.

Targets MCP authorization spec revision 2025-06-18 (stable). The 2026-07-28 release candidate adds six SEPs that are tracked separately in #100 for v1.x; v1 ships against stable. Verification thread: #86 comment 2026-05-19. Reviewer credit: @Ilya0527, @supertrained.

Stages

Tracked as GitHub sub-issues — sidebar shows live status. Parent closes when Stage 7 (#97) merges.

Stage	Scope	Sub-issue	Status
1	RFC 7591 Dynamic Client Registration	(no sub — pre-carve)	✅ Shipped (PR #89)
2	RFC 9728 PRM + RFC 8414 AS metadata + JWKS placeholder	#92	🟡 In review (PR #90)
3	/oauth/mcp/authorize (PKCE-S256, bridges to upstream IdP)	#93	⬜ Pending
4	/oauth/mcp/token + JWT signing + refresh rotation	#94	⬜ Pending
5	withMCPAuth wrapper + 401 + WWW-Authenticate contract	#95	⬜ Pending
6	Audit events + onMCPTokenIssued hook	#96	⬜ Pending
7	End-to-end integration fixture (v1 conformance proof)	#97	⬜ Pending
8	User-facing docs	#98	⬜ Pending

Cross-cutting decisions

These apply across stages; each sub-issue inherits them.

• Token format: JWT, Harper-signed, audience-bound (aud claim drives RFC 8707 validation; no token-table round trip; RFC 9068-aligned).
• Signing algorithm: RS256 default, EdDSA optional via config; advertised in AS metadata.
• Signing keys: persisted in harper_oauth_mcp_keys table — file storage would diverge across replicated Harper nodes.
• DCR storage: persisted in harper_oauth_mcp_clients — Claude Desktop caches client_id, ephemeral store breaks across restarts.
• DCR access: open by default per RFC 7591; production deployments use initialAccessToken to gate.
• Refresh tokens: rotated single-use per OAuth 2.1; replay revokes the family.
• Token scoping: role-level (matches human OAuth); per-tool scoping is v1.1.
• Transitive revocation when upstream IdP session ends: not in v1 — spec doesn't require it. Future onUpstreamRevoked hook lands in v1.1 for apps that need it.
• Canonical resource URI: configurable per app (mcp.resource), defaults to <issuer>/mcp. Issuer should be pinned in production via mcp.issuer (otherwise derived from request Host header).

Dependencies

• Independent of HarperFast/harper#465 v1. Apps with their own MCP integrations (heskew/harper-kb, Cortex MCP server, custom apps) can adopt this immediately.
• Soft alignment: when HarperFast/harper#465 v1.1 adds OAuth to native MCP, it should delegate to this plugin, not run a parallel implementation. Track as a coordination point when that lands.

Related

• HarperFast/harper#465 — Native MCP server in Harper core
• HarperFast/harper#623 — Final v1 PR for native MCP (defers OAuth to v1.1)
• HarperFast/harper#612 — Agent-loop orchestration (downstream consumer)
• MCP authorization spec, revision 2025-06-18: https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization

Out of scope

• OAuth in the native MCP server itself (that's HarperFast/harper#465 v1.1)
• Tool-scoped OAuth tokens (v1.1; v1 matches human-OAuth role-level access)
• Transitive revocation tied to upstream IdP sessions (v1.1, via onUpstreamRevoked hook)
• Token introspection / revocation endpoints (RFC 7662 / RFC 7009 — short TTL + refresh rotation is the spec's answer)
• Cross-instance MCP token federation

---

🤖 Generated with Claude Code

[heskew]

Thanks — capturing these here so they're not lost. Will verify against the current MCP authorization spec (2025-06-18) before refreshing the issue:

• Protected Resource Metadata (RFC 9728) and the WWW-Authenticate: Bearer resource_metadata="..." 401 discovery contract.
• Dynamic Client Registration (RFC 7591) and whether it's effectively required by the common MCP clients.
• RFC 8707 resource parameter and audience-bound token issuance.
• Token transitivity when the upstream IdP token expires or is revoked.

---

🤖 Posted by Claude on Nathan's behalf

---

[update] looks like those comments from Ilya0527 are gone...

[supertrained]

The acceptance list will be easier to verify if it turns into one route-card fixture before implementation.

A concrete first fixture could be:

• Route: unauthenticated GET /mcp returns 401 with WWW-Authenticate: Bearer resource_metadata="..." pointing at the protected-resource metadata document.
• Allowed lane: DCR-created client_id + PKCE + resource=<canonical MCP resource URI> produces a token that is valid only for that MCP resource.
• Denied neighbors: auth-server metadata exists but PRM is missing; /token omits or mismatches resource; a registered client disappears after process restart; a revoked upstream provider session still authorizes MCP traffic when transitive revocation is expected.
• Authority owners: upstream IdP account/user, downstream MCP client registration, MCP resource URI, token/session store, and audit event id.
• Receipts: PRM JSON, AS metadata including registration_endpoint, token audience/resource claim, session-bridge lookup, and typed 401 / invalid_target / invalid_client failures.

If there is already one concrete Harper app route in mind — for example the first /mcp route in harper-kb or the native server follow-on — I would start with a minimal positive/negative fixture pair around that one route before generalizing across providers. The useful proof is not just “OAuth works”; it is “this MCP route can prove which actor, resource, client, and backend session authority it admitted, and exactly which neighboring request it refused.”