Frequently Asked Questions About Rachel Lee's Agentic Web Publishing Framework
21 answers covering everything from basics to advanced usage.
// Basics
Can I use the Agentic Web Publishing Framework on a static site with no backend?
You can partially implement it. Web MCP works on any HTML page, so in-browser agents can interact with static pages via declarative or imperative registration. However, MCP tools and MCP Apps require a server-side component to handle HTTP transport and tool execution. You would need to add a minimal server layer (e.g., a serverless function or lightweight HTTP server) to expose MCP tools and serve MCP App bundles.
Do I need to know MCP to use this framework?
You need a working understanding of MCP concepts — tools, resources, transport layers — but you do not need deep protocol expertise. The framework provides clear mappings: your site's navigation actions become MCP tools, your bulk content becomes MCP Resources, and your interactive pages become MCP Apps. If you can build a REST API and write HTML/CSS/JS, you have the technical foundation to implement this framework.
What is the starfish design and why should I avoid it?
The starfish design is Rachel Lee's term for a chatbox landing page where the entire interface is a blank prompt field. It forces users to guess what they can do — like a command line before graphical interfaces existed. It is a transitional pattern, not a destination. Instead, use MCP Apps to provide visual structure, guided navigation, and interactive elements that reduce the discovery burden on users.
Can I implement only part of the Agentic Web Publishing Framework?
Yes. The framework supports incremental adoption. You can start with just MCP tools and HTTP transport to make your content accessible in agent harnesses like Claude Desktop. Add MCP Apps later when you need rich interactive responses. Add Web MCP registration when you want to support in-browser agents. Each layer is independent and adds value on its own, though the full framework delivers the complete 'One Server, Three Clients' vision.
What is the Mother May I pattern in MCP Apps?
It is Rachel Lee's term for the permission-mediated architecture inside MCP Apps. Because MCP Apps run in sandboxed iframes with no local storage and no direct network access, every external action — fetching server data, opening a link, navigating — must be requested through the agent harness. The app calls call_server_tool for data and uses the host-permission API for links. Nothing happens without the harness's explicit approval.
// How To
Should I use stdio or HTTP transport for my MCP server?
Default to HTTP transport for any public-facing or user-facing MCP server. Users connect by pasting a single URL — zero config-file editing. Stdio transport requires users to configure a JSON file with command-line arguments, which is high friction for non-technical users. Stdio is acceptable only for internal developer tooling where users are comfortable with config files and local process management.
How do I bundle an MCP App into a single file?
Use a build tool like Vite with a single-file plugin to bundle your HTML, CSS, and JavaScript into one self-contained HTML file. Embed images and icons as base64 data URIs. Reference fonts and CSS from your own server origin via CSP configuration. The result is a single file that the MCP tool returns and the agent harness renders in a sandboxed iframe. No external dependencies should be assumed available.
How do I add Web MCP to an existing HTML page?
For forms, add tool-name and tool-description attributes to your form elements — this is the declarative model. For JavaScript-driven interactions, use navigator.modelContext.registerTool(name, description, inputSchema, callbackFn) — the imperative model. Always wrap imperative registration in a check: if (navigator.modelContext) to ensure graceful degradation for non-agent browsers. The callback function can be the same function your UI already uses for that action.
How do I handle external links inside an MCP App?
Standard href links and window.open do not work inside MCP Apps because the app runs in a sandboxed iframe. Use the host-permission pattern instead — call the agent harness's link-opening API (e.g., appref current open_link) to request that the host open the URL. This is part of the 'Mother May I' pattern where all external actions require permission from the agent harness.
How do I test that my site works for all three client types?
Test in three ways: (1) Open your site in a regular browser and confirm it works normally for human users. (2) Install your HTTP MCP server in Claude Desktop or an equivalent agent harness and verify all tools appear, return correct data, and render MCP Apps properly. (3) 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.
// Troubleshooting
Why are my fonts and images not loading in my MCP App?
MCP Apps run in sandboxed iframes where external resources are blocked by default. You must configure your server's Content Security Policy (CSP) to explicitly allow the origins your fonts, images, and stylesheets come from. Resources from domains not listed in the CSP will fail silently — no error messages, just blank spaces or missing styles. For maximum reliability, embed resources as base64 or serve them from your own origin.
Why is the AI model narrating my tool's JSON response instead of letting the MCP App handle it?
You likely have a navigation or data tool intended to be consumed by the MCP App itself, but you have not set visibility: app on that tool. Without this setting, the model treats the tool's response as content to present to the user and attempts to narrate it as text. Set visibility: app on any tool whose response should be consumed silently by the MCP App rather than surfaced in the chat.
My MCP App cannot fetch data from my server — what is wrong?
MCP Apps have no direct network access from their sandboxed iframe. Any data fetch or server-side action must go through call_server_tool, which mediates the request through the agent harness. This is the 'Mother May I' pattern. Refactor your app's fetch calls to use call_server_tool instead, and ensure corresponding MCP tools exist on your server to handle those requests.
// Comparisons
How is the Agentic Web Publishing Framework different from just building an API?
An API exposes data endpoints but does not address agent discovery, interactive rendering inside agent harnesses, or in-browser agent access. This framework layers MCP tool definitions (with descriptions agents read to decide when to call them), MCP Apps for rich interactive responses rendered inline, and Web MCP for browser-based agents — all on top of your existing server. It is a full agent-accessibility strategy, not just data exposure.
How does the Agentic Web Publishing Framework compare to building a custom GPT or Claude project?
Custom GPTs and Claude projects are closed environments where you upload content to a specific platform. The Agentic Web Publishing Framework keeps your content on your own server and makes it accessible across multiple agent harnesses simultaneously via open MCP standards. You maintain control, serve all three client types from one backend, and avoid vendor lock-in to a single AI platform.
// Advanced
Can I use Web Speech API and other browser APIs inside MCP Apps?
Yes. Browser primitives like Web Speech API, Web Animations API, Canvas, WASM, and Audio API are available inside the sandboxed iframe of an MCP App. Rachel Lee calls the browser an 'Infinite Canvas' precisely because these APIs enable rich interactive experiences at zero inference cost. Always check whether a browser primitive can do what you need before reaching for an external LLM call or third-party service.
Is Web MCP the same as MCP?
No. Web MCP is inspired by MCP but is not spec-compliant with it. Web MCP is a browser-side mechanism that turns HTML pages into mini tool servers for in-browser agents, using either HTML attributes or JavaScript registration. The MCP spec governs server-to-agent-harness communication via stdio or HTTP transport. The two may continue to diverge, so build for the abstraction rather than assuming convergence.
How many MCP tools should I expose for my site?
Match your MCP tool count to your site's navigation surface area, not your internal function count. If your site has list, search, filter, and detail views, you need roughly four to six tools. Over-exposing internal functions clutters the agent's tool list and increases the chance of misuse. Keep tools focused on what a user would naturally ask for — list_episodes, search_by_topic, get_page — not internal helpers.
What should MCP tool descriptions contain?
Tool descriptions are read by the AI agent to decide when to call the tool, so write them as clear natural-language explanations of what the tool does and when it is useful. Include the type of data returned (JSON list, Markdown text, interactive app) and any constraints. Avoid jargon-heavy internal naming. Think of descriptions as instructions to a smart assistant who has never seen your site before.
Should I use MCP Tools or MCP Resources for my documentation?
Use MCP Resources for bulk documentation and text corpora that should be loaded into agent context for background knowledge. Use MCP Tools for targeted retrieval — searching docs, listing API methods, getting a specific guide. A common mistake is using Tools to inject large documentation one chunk at a time, which wastes context tokens. Resources are the correct vehicle, even though agent harness UI support is currently limited.
How do I prevent my MCP App from breaking when the agent harness updates?
Build against the documented abstractions (call_server_tool, host-permission link API, visibility settings) rather than harness-specific implementation details. Keep your MCP App as a self-contained bundle with minimal assumptions about the host environment. Test regularly across Claude Desktop and other harnesses. Since MCP and Web MCP may evolve independently, avoid coupling tightly to either spec's current behavior.