MCP OAuth Stage 8: user-facing docs

[heskew]

MCP OAuth Stage 8: user-facing docs

Sub-issue of #86. Full quickstart and reference docs for app authors adopting MCP OAuth — supersedes the deferred-to-Stage-8 work-in-progress notes shipped piecemeal during Stages 1 and 2.

Context

Stages 1 and 2 added minimal security-focused documentation (the initialAccessToken lockdown gate, the well-known endpoints table, the Host-header issuer caveat). Those were necessary for operators of the merged PRs — but they're not enough for app authors to actually adopt MCP OAuth as a feature. This stage lands the "10 lines and your Harper app speaks MCP OAuth" quickstart and the full reference once the API surface is complete.

What this adds

1. README section: "MCP OAuth" — top-level feature surface with the 10-line config + code snippet quickstart
2. docs/mcp-oauth.md — new dedicated doc covering:
   • The full flow diagram (PRM → AS metadata → DCR → authorize → token → bearer auth)
   • Configuration reference for the mcp block (already partially in docs/configuration.md; expanded here)
   • withMCPAuth wrapper usage with examples
   • The onMCPTokenIssued hook with use cases (rate limiting, billing)
   • Production deployment notes: pin mcp.issuer, set initialAccessToken, HTTPS, redirect URI allowlist
   • Troubleshooting: common MCP-client config errors, how to read the audit events
3. docs/configuration.md updates — remove the "(work in progress)" markers from the MCP section once everything is stable; expand the security-considerations subsection
4. Migration note — for apps that previously rolled their own MCP OAuth, what to swap out
5. Cross-references — README links to docs/mcp-oauth.md; docs/mcp-oauth.md links to RFCs and the MCP authorization spec

Spec requirements

• No spec MUST/SHOULD on documentation. Best practice: docs should let an integrator securely configure the feature without reading source.

Acceptance

• README has an MCP OAuth section with the 10-line quickstart
• docs/mcp-oauth.md exists and covers config, the wrapper, the hook, production deployment, troubleshooting
• All "(work in progress)" markers removed from docs/configuration.md MCP section
• Every config option documented with type, default, and security implication if any
• Production-deployment checklist included (HTTPS, pinned issuer, gated DCR, redirect URI allowlist)
• Links to MCP authorization spec 2025-06-18 and the cited RFCs (7591, 8414, 8707, 9728, 6750)
• No code samples advertise features that don't exist yet (e.g., per-tool scoping, transitive revocation — both v1.1)

Dependencies

• Depends on: Stages 1–6 (everything to document must exist) — practically also Stage 7 (the integration fixture is the source of the "10-line snippet" we reference)
• Blocks: none — the parent Add MCP OAuth flow support #86 is the v1 milestone; Stage 7 + Stage 8 together close it

Out of scope

• v1.1 docs (per-tool scopes, transitive revocation, native MCP server composition) — separate issue once those features land
• API reference auto-generation (out of scope for the OAuth plugin)
• Migration guides for app frameworks other than Harper

---

🤖 Generated with Claude Code