MCP OAuth Stage 8: user-facing docs (#98)

[heskew]

Closes #98 — Stage 8 of the MCP OAuth epic (#86). App-author documentation for MCP OAuth.

Its dependencies — #134 (withMCPAuth) and #141 (audit + onMCPTokenIssued) — are both merged, so this is unblocked. Docs-only; merges cleanly into current main (#141 touched no docs).

What's added / changed

• docs/mcp-oauth.md (new) — the single deep guide: end-to-end flow diagram, endpoint reference (discovery / authorize / token / JWKS), the withMCPAuth wrapper (both registration models, options, cross-component use via getConfig), the onMCPTokenIssued hook, audit events (all three types, incl. oauth.mcp.token.rejected), a production-deployment checklist, troubleshooting, and a migration guide from a hand-rolled MCP authorization server. Links the MCP authorization spec (2025-06-18) and RFCs 6749/6750/7591/7636/8252/8414/8707/9728.
• README.md — MCP OAuth section trimmed to a quickstart (config + withMCPAuth) plus a pointer to docs/mcp-oauth.md; added the doc to the index.
• docs/configuration.md — dropped the "(work in progress)" marker; documented signingKeyPem, signingAlgorithm, accessTokenTtl, refreshTokenTtl; fixed the JWKS note; trimmed the inline withMCPAuth how-to to a pointer + a security note.
• docs/lifecycle-hooks.md — documented onMCPTokenIssued (the MCP-client analog of onLogin), reflecting MCP OAuth Stage 6: audit logging + onMCPTokenIssued hook (#96) #141's fire-and-forget / not-awaited behavior.

Design: single source of truth

#134 had already landed withMCPAuth walkthroughs in both README.md and docs/configuration.md. To avoid three copies that drift, the deep wrapper/flow/hook material now lives once in docs/mcp-oauth.md; README.md and configuration.md carry short pointers into it (so those two files are net-trimmed here).

Notes

• Docs-only; no code changes.
• prettier --check clean; all internal anchors resolve.
• No v1.1 features advertised — per-tool scopes and transitive revocation are explicitly listed as not-yet-supported.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces comprehensive documentation for the experimental MCP OAuth feature, enabling the plugin to act as an OAuth 2.1 authorization server for Model Context Protocol clients. The updates span the README, configuration reference, lifecycle hooks, and a new dedicated guide detailing the flow, endpoints, and the withMCPAuth wrapper. Feedback suggests adding the package property to the README's configuration snippet to ensure consistency and correct plugin resolution.

[heskew]

Developer Experience (DevExp) Review

This documentation PR is outstanding and extremely thorough. It anticipates real-world integration hurdles (such as multi-component getConfig static-scope resolution, cluster PEM key-drift, and middleware Basic/Bearer header conflicts) and handles them proactively.

Here are a few highly focused, non-blocking suggestions to refine the developer experience and achieve absolute documentation perfection:

1. Harmonize timing/execution language for onMCPTokenIssued

• Files: docs/lifecycle-hooks.md:332 and docs/mcp-oauth.md:321
• What: Wording in lifecycle-hooks.md says the hook is called "before the response returns", whereas mcp-oauth.md says it "runs detached — it is not awaited... Because it isn't awaited, its side effects may complete after the client already has the token".
• Why it matters: If developers read "before the response returns," they might expect to block/delay the response or expect their side effects to finish synchronously before the client receives the token.
• Suggested Fix: Harmonize the language in lifecycle-hooks.md to make the async/detached execution clear:

  - Called after an MCP access or refresh token is minted, before the response returns.
  + Invoked after an MCP access or refresh token is minted. Because it runs detached and is not awaited (fire-and-forget), it never delays the token response, and its side effects may complete after the client has already received the token.

2. Remove unused next parameter from Quickstart handler

• File: docs/mcp-oauth.md:54
• What: The quickstart handler definition includes an unused next argument:

  function mcpHandler(request, next) { ... }

• Why it matters: Since the endpoint is registered as a leaf handler on a urlPath subroute (server.http(withMCPAuth(mcpHandler), { urlPath: '/mcp' })), it doesn't utilize or need next. Including next adds unnecessary cognitive load and suggests middleware-like chaining behavior.
• Suggested Fix: Simplify the quickstart signature:

  function mcpHandler(request) {
  	const { sub, client_id, scope } = request.mcp; // verified token claims
  	return { jsonrpc: '2.0', result: { hello: sub } };
  }

3. Add explicit context for JSON-RPC response format

• File: docs/mcp-oauth.md:56
• What: The quickstart example returns { jsonrpc: '2.0', result: { hello: sub } }.
• Why it matters: For developers unfamiliar with MCP internals, returning a JSON-RPC payload instead of standard REST JSON could look confusing or arbitrary.
• Suggested Fix: Add a brief code comment explaining that MCP communicates using the JSON-RPC 2.0 protocol:

  function mcpHandler(request) {
  	const { sub, client_id, scope } = request.mcp; // verified token claims
  	// MCP endpoints communicate using JSON-RPC 2.0 (carried over SSE or stdio)
  	return { jsonrpc: '2.0', result: { hello: sub } };
  }

---

Reviewed by Antigravity (Advanced Agentic Coding, Google DeepMind) 🚀

[heskew]

All three addressed in e5c586b: (1) harmonized the onMCPTokenIssued timing language in lifecycle-hooks.md to the not-awaited/detached wording (it contradicted mcp-oauth.md); (2) dropped the unused next param from the quickstart handler; (3) added a JSON-RPC 2.0 note on the quickstart return shape.

[heskew]

docs/mcp-oauth.md:161 has the path-appended Protected Resource Metadata URL backwards. For a resource like https://host/mcp, the implementation builds and serves /.well-known/oauth-protected-resource/mcp (PRM_PATH + resource path), and withMCPAuth advertises that form in WWW-Authenticate. The current text says /mcp/.well-known/oauth-protected-resource, which sends users/proxies to the wrong route. Please flip the example to /.well-known/oauth-protected-resource/mcp.

---

🤖 Posted by Codex (gpt-5.5) on Nathan's behalf

[heskew]

Fixed in 3972763 — flipped both occurrences to the correct RFC 9728 form /.well-known/oauth-protected-resource/mcp (matching wellKnown.ts protectedResourceMetadataUrl = origin + PRM_PATH + resource path). The bare root-resource mentions were already correct.