Document subscribe on custom MCP resources

[kriszyp]

⊙ Problem

Let MCP clients subscribe to custom mcpResources URIs (harper#3257) adds an optional subscribe to static mcpResources entries. Today the MCP reference says only row-backed resources are subscribable. It does not say what an author's subscribe method must return, or when Harper releases the stream.

🤔 Should the docs commit to the release order: end(), otherwise the iterator's return()?

Yes. An author cannot write a correct stream without knowing it. Clients see the refusal of a generator, or of a stream that has neither, as -32603. The implementation's tests pin that order.

💡 Solution

• reference/mcp/tools-and-resources.md: a new "Subscribing to custom resources" section.
  • It covers the field, a table-backed example, and the contract: authorize before returning, release, access after subscribe, workers and errors.
  • The invalid-entry list now covers a bad subscribe.
• reference/mcp/subscriptions.md:
  • Custom resources join the subscribable URIs.
  • A new table lists the JSON-RPC errors returned when a subscribe fails.
  • The statements that hold only for row-backed resources now say so: changes-only delivery and the audit-log feed.
  • Reconnect restore runs in the background. It keeps URIs whose subscribe failed or that have no match on the worker yet.
• reference/mcp/overview.md: the feature list mentions custom subscriptions.
• release-notes/v5-lincoln/5.4.md: an entry under Subscriptions.

🤔 Is authorizing once, at subscribe time, enough?

That is what the implementation does, and the page says so:

• Harper ends the stream when the identity lapses.
• Authors must enforce resource-level access after subscribe.
• Notifications carry only the URI, and the client's re-read is authorized again.

🤔 Why does the sample's own gate answer -32603 rather than permission denied?

It reuses the page's read-example gate, which throws a plain Error. Only an AccessViolation maps to -32602 permission denied, as the Errors bullet states, and the harper package does not export that class (harper index.ts).

🤔 Should the HTTP 500 → JSON-RPC error change get its own release-note heading?

No. It lands in the same entry because one PR made both changes. The old answer was already a JSON-RPC envelope, only with status 500.

✅ Verification

• Each behavior claim was checked against harper#3257 at ff6b85701: error strings, release order, generator handling, scoped-token lifetime and restore concurrency.
• The example's subscribe call has the same shape as the table-backed one in the harper integration fixture, which is tested end to end. The example itself was not run as written.
• npm run build succeeds with no broken links or anchors, and npm run format:check is clean.
• Pre-push review: five rounds, two of them full, by Codex, Gemini, Cursor Composer and Cursor Muse, with Harper domain adjudication. Fixed along the way:
  • the example's empty get stub;
  • subscribing through the base table class;
  • the scoped-token and anonymous-session lifetimes;
  • row-backed-only statements;
  • the missing release-note entry.
  • inline version badges, now plain text per CONTRIBUTING.md (raised by Gemini on the PR).
• One reviewer note stays open by nature. On 2026-10-17, harper had no v5.4 tag or branch, and the newest tag was v5.3.2. So v5.4.0 is the first release that can carry this; recheck the tags before merge.

_{🤖 Generated by Claude Code (Claude Opus 5.5); posted via @kriszyp.}

🤖 Generated with Claude Code

https://claude.ai/code/session_019W6f2CJA6oE5ixf6S2b4Ah

Related PRs: none found
Complexity: easy

_{Review-Coverage: authored=claude; ran=gemini,cursor-composer,codex,cursor-muse; adjudicated=domain; declined=cursor-grok,cursor-kimi,muse; rounds=5; full=2 @ c24c6a9}

_{Review-Attention: skim ~2m (decisions: inline-version-marker-form, example-auth-via-get-override, error-shape-change-placement) @ c24c6a9}

[gemini-code-assist]

Code Review

This pull request updates the Harper Model Context Protocol (MCP) documentation and release notes for version 5.4.0, detailing how MCP clients can now subscribe to custom resources using a new subscribe method. The review feedback recommends avoiding the use of the <VersionBadge> component mid-sentence in running prose across several files, suggesting plain text alternatives instead to improve readability.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-734

This preview will update automatically when you push new commits.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-734

This preview will update automatically when you push new commits.