Frequently Asked Questions About Rachel Lee's Agentic Web Publishing Framework
21 answers covering everything from basics to advanced usage.
// Basics
What are the three client types this framework serves?
The three clients are: humans in browsers (your normal website visitors), humans using agents (people operating Claude Desktop, Copilot, or similar harnesses), and agents browsing autonomously (in-browser agents acting without direct human steering). The architectural goal — 'One Server, Three Clients' — is to serve all three from a single backend deployment rather than building separate experiences.
What does 'Meet Them Where They Are' mean in this framework?
It means your audience is already working inside agents, so you shouldn't wait for them to return to your website — publish your content and tools into the agent surfaces they already inhabit. The web's job has always been to reach people wherever they are, and agents are the new 'wherever.' You bring your site to the agent instead of pulling the user back to the browser.
What is the 'infinite canvas' idea?
The infinite canvas is Rachel's framing that the browser — and by extension the agent harness — is a rendering surface for anything, not just documents. CSS, JavaScript, Web Speech, Canvas, WASM, Animation, and Audio APIs are the language of interactive experiences. Inside MCP Apps you can use these primitives to go beyond chat walls of text and build video, audio, and interactive components.
Do I have to target all three client types at once?
No. You can target one, two, or all three client types depending on your goals. A developer-focused docs site might prioritize agent users and in-browser agents; a public media archive might focus on human browsers and agent users. Identify which clients matter for your use case, then apply the relevant parts of the workflow — the single-backend goal still holds across whichever you choose.
// How To
How do I map my existing site navigation to MCP tools?
List every navigation action a human takes on your site — list, search, filter, view detail, paginate — and make each a candidate MCP tool. Name tools to match what users naturally ask for, like list_comics, search_by_character, get_transcript, or get_page. Return structured JSON for data tools and Markdown for text-rich content. Keep the tool count focused to mirror your site's navigation, not every internal function.
How do I build an MCP App from my existing design system?
Bundle your HTML, CSS, and JavaScript into a single self-contained file (for example with Vite's single-file plugin), then add the meta attribute `ui` pointing to a URL on your server so the tool returns the app instead of raw data. To reuse your existing fonts and CSS, serve them from the same origin and configure a CSP that allows those resources. Embed everything else as base64.
How do I add Web MCP to a form-based page versus a JavaScript-driven page?
For form-based pages, use the declarative model: add tool-name and tool-description attributes to your form elements. For JavaScript- or API-driven pages, use the imperative model: call navigator.modelContext.registerTool(name, description, inputSchema, callbackFn), reusing the same function that already powers that action. Always check `if (navigator.modelContext)` before registering so non-agent browsers degrade gracefully.
How do I test that my site works across all three client types?
Run three checks. First, confirm your website still works normally in a browser. Second, install your HTTP MCP server in Claude Desktop or equivalent and verify all tools appear and return correct data and apps. Third, use the MCP B browser extension as a debugging harness to confirm your Web MCP tools are registered, visible, and callable by the model on each page.
// Troubleshooting
Why does my MCP App render blank or broken when it loads external fonts?
Because external resources are blocked by default inside the sandboxed iframe and fail silently. You must explicitly configure a Content Security Policy (CSP) on your server that allows the external origins for your fonts, images, or stylesheets. Any resource not covered by the CSP won't load, producing a blank or broken app with no obvious error.
Why aren't my links working inside an MCP App?
Standard href and window.open don't work inside an MCP App because it's sandboxed. Links require explicit host permission via the agent harness's link-opening API — use the host-permission pattern (`appref current open_link`) instead. This is part of the 'Mother May I' pattern: the app can't take navigation actions directly and must request them from the host.
Why is the model narrating my app's navigation tool responses as text?
Because the tool's visibility is set incorrectly. For navigation tools that the app itself calls and that shouldn't surface to the user as messages, set `visibility: app`. Without it, the model may attempt to narrate the tool's JSON response as text instead of letting the app consume it silently. This signals the response is meant for the app, not the user.
Why can't my MCP App fetch data or store state?
MCP Apps run in a sandboxed iframe with 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. If you assumed the app could hit an API directly or persist state locally, that's the cause; route all server-side data and actions through call_server_tool instead.
// Comparisons
How does this framework compare to serving docs through MCP tools one chunk at a time?
Injecting large documentation corpora into context via MCP tools one call at a time is inefficient use of context. This framework recommends MCP Resources for bulk content priming instead — they're the correct MCP construct for serving documents and corpora to agent context. Reserve tools for the discrete navigation actions users ask for, and use Resources to pre-prime full content.
How does Web MCP compare to letting agents navigate via screenshots?
Screenshot-based navigation forces agents to run visual model inference and traverse the DOM, which is costly and unreliable. Web MCP lets an in-browser agent call your registered tools directly — reusing the same internal API functions your UI already uses — bypassing DOM traversal and visual inference entirely. This reduces token cost and improves reliability for actions like create_item or filter_by_status.
How does an MCP App compare to returning a JSON blob from a tool?
A JSON blob works for data the model needs to reason over, but it produces walls of text and puts discovery burden on the user. An MCP App returns an interactive experience rendered inline — with navigation, visual cues, and browser-primitive features like text-to-speech. Match the return type to what the user needs to do: JSON for data, Markdown for text, MCP Apps for interactive or visual content.
How does HTTP transport compare to stdio transport for user experience?
HTTP transport is low-friction: users paste one URL into their agent harness settings and they're done, making it ideal for public-facing servers. Stdio (Studio) transport runs the server as a local process and forces users to edit a JSON config file with command-line arguments — high friction, appropriate only for developer or internal tooling. Default to HTTP for anything public.
// Advanced
Should I use MCP Tools or MCP Resources for my documentation?
Use MCP Resources for bulk documentation priming and MCP Tools for discrete navigation actions. Expose list_guides, list_api_methods, and search_docs as tools, but serve the full documentation corpus via Resources so harnesses can pre-prime context when a user switches to your library's mode. Note that Resources are currently poorly supported in agent harness UIs despite being the correct vehicle for large content.
How do I decide how many MCP tools to expose?
Expose the same conceptual surface area as your site's navigation — not every internal function. Focus on the actions users would naturally ask for: list, search, filter, view detail, get transcript, get page. Over-exposing internal functions bloats the tool list and confuses the agent's tool-selection reasoning. Keep it focused so descriptions stay clear and the agent reliably picks the right tool.
What is the 'Mother May I' pattern and when does it apply?
The 'Mother May I' pattern is the permission-mediated behavior inside MCP Apps where the app cannot take network or navigation actions directly and must request them from the host. It applies to any external data fetch (via call_server_tool) and any link opening (via the host-permission link API). Because the app is sandboxed with no local storage or direct network access, all such actions route through the host.
Should I assume Web MCP and MCP will converge into one spec?
No — treat Web MCP as inspired by but not spec-compliant with MCP, and build for the abstraction rather than assuming convergence. The specs may continue to diverge. Web MCP makes each HTML page a mini tools server for in-browser agents using declarative attributes or the imperative registerTool API, but its mechanics differ from the MCP transport-based model. Design so your implementation survives divergence.
Can I replicate my full website experience inside an agent harness?
Yes. Rachel's media archive example maps navigation to tools (list_episodes, search_by_topic, get_transcript returning Markdown, get_page returning an MCP App), then builds get_page as a single-file bundle using the existing design system. The app includes forward/backward navigation via call_server_tool and a text-mode toggle that surfaces the transcript inline — replicating the full website experience inside the agent harness.