Skip to content

docs: add add-apps-to-host skill for building MCP Apps hosts - #859

Closed
thoo wants to merge 1 commit into
modelcontextprotocol:mainfrom
thoo:docs/add-apps-to-host-skill
Closed

thoo wants to merge 1 commit into
modelcontextprotocol:mainfrom
thoo:docs/add-apps-to-host-skill

Conversation

@thoo

@thoo thoo commented Nov 15, 2026

Copy link
Copy Markdown

Problem

The repo ships skills for building MCP Apps (create-mcp-app, add-app-to-server, convert-web-app, migrate-oai-app). Nothing covers the other side of the protocol: a chat client that wants to render MCP Apps. Host authors have to reverse-engineer examples/basic-host and the spec to learn which pieces to build, in what order, and which security rules are mandatory. Most mistakes happen in the browser parts, the sandbox proxy page and the component that owns the iframe and AppBridge: a sandbox on the same origin as the host, CSP in a meta tag, sending tool input before initialized, or no visibility check on app-initiated tool calls.

Solution

  • New skill plugins/mcp-apps/skills/add-apps-to-host/:
    • SKILL.md: the four pieces a host builds; AppFrame vs AppBridge; the required startup order; which handler to register for each app request; the four UI↔model routes (quiet context update, ui/message, app-initiated tool calls, app-provided tools); re-drawing saved chats; a test plan using the repo's example servers; the spec and security rules; a table of common mistakes.
    • references/sandbox-proxy.md: the sandbox page and relay with an exact-origin allow-list, plus a sandbox server that sends the app's CSP as an HTTP header. Derived from basic-host.
    • references/app-frame.md: a framework-agnostic AppFrame module (queues everything until initialized, graceful teardown, theme and size sync, app-provided tools) and a React wrapper that is safe under Strict Mode.
    • references/backend-contract.md: advertising the UI extension, filtering and enforcing tool visibility, the app events streamed to the browser, and the endpoints the AppFrame calls. Written for hosts that keep MCP clients on the backend, with notes for the browser-held client pattern basic-host uses.
  • docs/building-a-host.html: a standalone visual explainer of the same material for humans, with step-through sequence diagrams.
  • Lists the new skill in docs/agent-skills.md, the plugin README and AGENTS.md (which was also missing two existing skills).

Testing

  • Type-checked every TypeScript block in the three reference files against the built SDK by compiling them inside examples/basic-host (strict tsconfig) from a throwaway folder (not committed). The only errors were ones caused by splitting the snippets apart (duplicate imports across sections, unused locals). No real type errors, so the markdown needed no changes.
  • Checked that the AppBridge/App APIs, handler names and notification methods cited in the skill exist in src/app-bridge.ts, src/app.ts and src/spec.types.ts, and that the ports in the test plan match examples/run-all.ts (3101+) and examples/basic-host/serve.ts (8080/8081).
  • Pre-commit hook: npm run build:all and prettier, both passed.
  • typedoc --treatValidationWarningsAsErrors --emit none passed.

Adds a fifth agent skill, add-apps-to-host, for building the host side of
MCP Apps in TypeScript: the sandbox proxy page on a separate origin, the
AppFrame component that owns the iframe and AppBridge, and the backend
endpoints they rely on. The skill walks through the required startup
order, the four UI-to-model routes, persistence and re-drawing, the
spec's security rules (origin split, CSP as an HTTP header, visibility
checks), common mistakes, and a test plan using the repo's example servers.

Also adds docs/building-a-host.html, a standalone visual walkthrough of
the same material, and lists the new skill in docs/agent-skills.md, the
plugin README and AGENTS.md.
@thoo thoo closed this Nov 15, 2026
@thoo
thoo deleted the docs/add-apps-to-host-skill branch November 15, 2026 03:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant