Teach Content share links to discover MCP access

[3mdistal]

Problem

When someone pasted a private Content share URL into an external agent, an ordinary page fetch ended at the browser access notice. The page did not tell the agent that an authenticated Content MCP connection could read the same document, so the agent could incorrectly ask the user to paste the document or conclude that access was impossible.

The existing share page must keep working unchanged for people. Public content, private access notices, social metadata, and authentication behavior should not gain agent-oriented UI.

Approach

Make the share response self-describing for agents while preserving the human surface. Both readable and private share pages now advertise a structured agent-context endpoint and include server-rendered MCP guidance that CSS removes from layout, focus, and the accessibility tree. Anonymous private context requests remain failures, but their JSON response explains the exact authenticated get-document call and same-instance connection path.

The guidance contains only the document ID already present in the URL. It does not expose a private title, body, owner, credential, or rejected token.

What changed

• Added a Content-owned MCP guidance descriptor with the /mcp endpoint, /mcp/connect setup path, and exact get-document { id } action shape.
• Added an application/agent-native+json alternate link and hidden server-rendered guidance to public and private share-page branches.
• Expanded anonymous private context denials with MCP recovery instructions while distinguishing missing credentials from invalid or expired tokens.
• Added route, context-endpoint, and shared-contract regression coverage.

Verification

• Three focused Vitest files pass with 12 tests, covering public/private discovery, denied responses, rejected-token handling, base paths, and the MCP argument contract.
• Content typecheck passes.
• SSR cache-shell, public agent-endpoint, secret-literal, default-chrome, silent-coercion, and changed-copy guards pass.
• Desktop and mobile browser checks confirmed the instruction remains invisible, has zero geometry, creates no tab stop, and is absent from accessibility snapshots and innerText.
• A fresh agent given only a private share URL fetched the page, discovered Content MCP, called get-document, and read the authorized fixture. A separate fresh fetch-first run recovered through the denied JSON guidance and MCP.
• Independent access/cache review found one prose mismatch between resourceId and id; it was corrected and covered by a regression assertion. No other findings remained.
• The machine-only alternate-link title carries a reviewed i18n-ignore reason; guard:i18n-changed-copy reports no affected copy surfaces.

Review focus

• Does the private denial reveal no information beyond the resource ID already supplied by the requester?
• Are the advertised MCP endpoint, connection path, and get-document { id } shape stable for supported hosts?
• Does the nonvisual discovery remain compatible with the repository's public, hard-cached SSR shell?

[github-actions]

Here's a visual recap of what changed:

Open the full interactive recap

[builder-io-integration]

Builder reviewed your changes — looks good ✅

Review Details

Incremental Code Review Summary

I reviewed the latest PR #5021 head and compared it with the prior clean review. The Content share route still adds only nonvisual MCP discovery metadata and the context endpoint still returns scoped recovery guidance for denied private documents. The private path exposes the requested document ID and stable MCP instructions, but not private title/body data or rejected credentials. Public and token-authorized reads remain on the existing access-controlled paths, and the /content base-path handling is consistent across the alternate link, structured discovery payload, and denial JSON.

This remains a high-risk review because it changes private-document access behavior and an agent-facing API contract. Two independent code-review passes found no new confirmed actionable issues. Supplemental live HTTP/raw-HTML checks passed for public/private rendering, discovery fields, token handling, no-leak denial responses, XSS escaping, and 400/404 behavior. Interactive browser verification was attempted twice, but Chrome tools were unavailable across all executor batches; visual/accessibility, mobile, and CSR editor checks remain environment-blocked.

🧪 Browser testing: Attempted after this review — Chrome tools were unavailable; HTTP/raw-HTML checks passed, but interactive visual verification remains environment-blocked.