Rachel Lee's Agentic Web Publishing Framework

// When should you use the Agentic Web Publishing Framework?

Use this skill when you have an existing web property (site, app, archive, documentation, dashboard) and want to make its content and functionality accessible inside AI agent harnesses like Claude or Copilot, as well as to in-browser agents. Also use it when designing a new web project that must serve all three client types from day one.

// What do you need before applying this framework?

• Existing web property or project scoperequired
  The website, archive, API, or web app you want to make agent-accessible. Describe its content types, navigation structure, and any existing APIs.
• Target client typesrequired
  Which of the three clients you are targeting: humans in browsers, humans using agents (e.g. Claude Desktop), agents browsing autonomously (e.g. in-browser agent). Can be one, two, or all three.
• Existing design system or component library
  Any shared CSS, fonts, or component bundles you already maintain. Used to build MCP Apps efficiently.
• Content structure
  How your content is organised — e.g. list/detail hierarchy, search indexes, transcript or text corpora, character or category taxonomies.

// What are the core principles of agentic web publishing?

// How do you make a website agent-accessible step by step?

1. 1

   Audit your content and map it to tool shapes

   List every navigation action a human would take on your site: list, search, filter, view detail, paginate. Each of these becomes a candidate MCP tool. Prefer tools that return structured JSON (lists, metadata) for data tools and Markdown for text-rich content like transcripts. Name tools to match what users would naturally ask for (e.g. list_comics, search_by_character, get_transcript, get_page).

2. 2

   Choose your transport layer

   If your users are non-technical and you want zero config-file friction: use HTTP transport. The user pastes one URL into their agent harness settings and is done. If your use case is internal tooling or developer-only: stdio (Studio) transport is acceptable, but requires users to edit a JSON config with command-line arguments — a high friction UX. Default to HTTP for any public-facing MCP server. Host it at a clean endpoint like /mcp.

3. 3

   Define and implement your MCP tools

   For each tool: write a clear description (the agent reads this to decide when to call it), define an input schema with only the fields truly required, and specify the return type. Keep tool count focused — expose the same conceptual surface area as your site's navigation, not every internal function. Avoid using MCP tools to inject large documentation corpora into context; that is what MCP Resources are for (even if client support is currently poor).

4. 4

   Build an MCP App for any tool that returns interactive or visual content

   An MCP App is a single self-contained HTML file (HTML + CSS + JS bundled, e.g. with Vite single-file plugin). Add the meta attribute `ui` pointing to a URL on your server to make a tool return an app instead of raw data. The app is sandboxed in an iframe with no local storage and no direct network access. Share your existing design system (fonts, CSS) by configuring a CSP (Content Security Policy) that allows your own server's resources. Embed everything else as base64.

5. 5

   Handle MCP App constraints explicitly

   Four constraints require deliberate handling: (1) External links — use the host-permission pattern (`appref current open_link`) not window.open or href. (2) External resources (fonts, images from other domains) — add them to the CSP config or they will silently fail. (3) Tool calls from inside the app — use `call_server_tool` for any action requiring server data; do not assume network access. (4) Tool visibility — for navigation tools called by the app itself that should not surface as text to the model, set `visibility: app` to prevent the model from attempting to narrate the JSON response.

6. 6

   Add Web MCP registration to your HTML pages for in-browser agents

   Web MCP makes each HTML page a mini MCP tools server for agents operating inside browsers. For sites with forms: add `tool-name` and `tool-description` attributes to your form elements (declarative model). For sites driven by JavaScript / API calls: use `navigator.modelContext.registerTool(name, description, inputSchema, callbackFn)` (imperative model). The callback is the same function you already use for that action. Check `if (navigator.modelContext)` before registering — degrade gracefully for non-agent browsers. Note: Web MCP is inspired by but not spec-compliant with MCP. Treat them as parallel, not identical.

7. 7

   Leverage existing browser APIs inside MCP Apps to avoid unnecessary inference

   Before reaching for an LLM or a third-party service for a capability, check whether a browser primitive already does it: Web Speech API for text-to-speech (zero dependency, zero inference cost), Web Animations API for motion, Canvas and WASM for compute, Audio API for sound. These are already available inside the sandboxed iframe of an MCP App. Use them to build rich, low-latency experiences.

8. 8

   Test across all three client types

   Verify: (1) Human in browser — does the site still work normally? (2) Human in agent — install your HTTP MCP server in Claude Desktop or equivalent, confirm all tools appear and return correct data and apps. (3) Agent in browser — use the MCP B browser extension as a debugging harness to confirm Web MCP tools are registered, visible, and callable by the model on each page.

// What does this framework look like in real projects?

// What mistakes should you avoid when publishing to agents?

• Using MCP tools to inject large documentation or text corpora into agent context one call at a time — this is an inefficient use of context. Use MCP Resources for bulk content priming instead.
• Defaulting to stdio (Studio) transport for public-facing MCP servers — it forces non-technical users to edit JSON config files with command-line arguments, creating unnecessary friction. Use HTTP transport.
• Forgetting that MCP Apps have no local storage and no direct network access — any stateful action or external data fetch must go through call_server_tool (the 'mother may I' pattern).
• Omitting CSP configuration when referencing external fonts, images, or stylesheets inside an MCP App — resources are blocked by default and fail silently, producing a blank or broken app.
• Using standard href or window.open for links inside an MCP App — links require explicit host permission via the agent harness's link-opening API.
• Setting tool visibility incorrectly for app-internal navigation tools — without `visibility: app`, the model may attempt to narrate the tool's JSON response as text rather than letting the app consume it silently.
• Treating Web MCP as fully spec-compliant with MCP — it is inspired by MCP but diverges. The specs may continue to diverge; build for the abstraction, not the assumption of convergence.
• Designing a 'starfish design' chatbox as the entire agentic interface — putting all discovery burden on the user is the agentic equivalent of a command-line interface. Supplement with MCP Apps and structured tool outputs.
• Ignoring existing browser primitives (Web Speech, Canvas, Audio, WASM) and reaching for external inference services instead — these APIs are available inside MCP Apps at zero inference cost.

// What are the key terms in agentic web publishing?

MCP App

An interactive rich-media experience returned by an MCP tool, created by bundling HTML, CSS, and JavaScript into a single self-contained file and rendered inline inside an agent harness. Distinct from a website: it is sandboxed, has no local storage, and requires server-mediated network access.

Studio transport (stdio)

The Standard Input/Output MCP transport where the server runs as a local process spawned by the client. Requires the user to configure a JSON file with command-line arguments. High friction for non-technical users; appropriate for developer/internal tooling.

HTTP transport

The web-based MCP transport where the server runs as a web service listening at an HTTP endpoint. Users connect by entering a URL in their agent harness settings. Low friction; recommended for any public-facing MCP server.

Web MCP

A browser-side mechanism that makes each HTML page a mini MCP tools server for in-browser agents. Comes in two flavours: declarative (tool-name and tool-description attributes on forms) and imperative (navigator.modelContext.registerTool with a callback). Inspired by but not spec-compliant with MCP.

Starfish design

Rachel's term for the chatbox landing page pattern where the interface is a blank prompt field that forces the user to do all discovery work. Analogous to the CLI before the GUI — a transitional phase, not the end state of agentic UX.

One Server, Three Clients

The architectural goal of serving humans in browsers, humans operating agents, and agents browsing autonomously from a single backend deployment.

Infinite Canvas

Rachel's framing of the browser (and by extension the agent harness) as a rendering surface for anything — not just documents, but video, audio, interactive components, and more — powered by existing web APIs.

Mother May I

Rachel's term for the permission-mediated pattern inside MCP Apps where the app cannot take network or navigation actions directly and must request them from the agent harness via call_server_tool or the host-permission link API.

MCP Resources

An MCP spec construct intended for serving bulk content (documents, corpora, assets) to agent context, distinct from Tools. Currently poorly supported in agent harness UIs despite being the correct vehicle for large content priming.

CSP (Content Security Policy)

The browser security mechanism that governs which external origins an MCP App's iframe may load fonts, images, and other resources from. Must be explicitly configured on the server; external resources are blocked by default.

call_server_tool

The mechanism by which an MCP App requests server-side actions or data fetches, since the app has no direct network access from within its sandboxed iframe.

visibility: app

A tool metadata setting that prevents the model from attempting to narrate or consume a tool's response as text, signalling that the response is intended to be consumed by the MCP App itself rather than surfaced to the user as a message.

// FREQUENTLY ASKED QUESTIONS