MCP App Hosts

MCP App Hosts

Reference skill for MCP App host environments and authoring your own host. Each host (VS Code, AppHub, standalone) has different CSP, sandbox, and capability constraints — this skill is the source of truth for what works where. It also documents how to build a custom host (AppHub-style LLM orchestration, or on the GitHub Copilot SDK).

This matrix lists only hosts that have been directly validated firsthand. Treat every unlisted host as unknown until its lifecycle, CSP, permissions, transport, accessibility and security behavior are recorded through hit-process.md.

Quick Capability Matrix

The generated Sampling/Elicitation rows are dated host observations for the legacy server-initiated APIs. In that compatibility profile, reverse requests require a stateful/bidirectional transport, an advertised client capability, and possibly host-specific authorization. In VS Code, App-button sampling requires the exact server entry under chat.mcp.serverSampling with allowedOutsideChat: true.

For new MCP 2026-07-28 work, use MRTR, subscriptions/listen, explicit application handles, or a direct model-provider connection as appropriate. See mcp-app-build/mcp-v2.md and mcp-app-build/sampling.md. Always ship a Display-Frame fallback where the interactive behavior is optional.

Media in VS Code: media-src 'self' blocks external audio/video URLs and the sandboxed iframe gets no autoplay / Web Speech grant. The _meta.ui.csp / sandbox.permissions opt-ins are spec'd but not honored by VS Code today. Proxy media through the server and return same-origin bytes (data: URL / embedded resource), played on a user gesture. See vscode.md §7.

VS Code is the most restrictive host in the currently validated set, but a pass there is not a guarantee for an unknown host. Validate lifecycle, permissions, accessibility and transport behavior on every declared target. See hit-process.md for recording evidence.

CopilotHub (GitHub Copilot SDK host) is a permissive custom host — its capability profile matches AppHub for every row above (full browser, about:srcdoc, popups allowed), plus a verified server→host sampling bridge (elicitation not implemented). See host-matrix.json (copilothub) and copilot-sdk-host.md.

Sub-Files

Usage

When building or auditing an MCP App, check the target host's capabilities:

1. Read host-matrix.json for programmatic checks
2. Read the host-specific file for detailed constraints and workarounds
3. If you discover something new, follow the HIT process to record it

Authoring a Host

Building your own MCP App host (not just targeting one)? Two reference implementations live here:

• apphub.md — LLM-orchestrated host: your own agent loop, an MCP Client proxy to downstream servers, manual postMessage bridge, splash + shared state.
• copilot-sdk-host.md — GitHub Copilot SDK host: feed servers into createSession({ mcpServers }), dual-channel architecture, hub-injected tools, hooks-based tool-call capture, result normalization, and a server→host sampling bridge. Start here for the tools: ["*"] and tool-capture gotchas.
• host-rendering.md — the web/React rendering side of any host: turning a tool result into an interactive iframe tile. iframe sandbox flags (interactivity vs display), per-tile CSP, reading the UI resource URI from both _meta shapes, theming tiles + host chrome for dark/light, the always-blocked PDF/plugin case and its escapes, and the host-side repair for the fragile "relay an opaque handle between two tools" pattern, and the sampling reverse-channel for tiles that borrow the host model (hint/AI buttons).

A host you author is also a target — once validated, add it to host-matrix.json via the HIT process so the build/test/audit skills account for it.

The Validated Portable Set

These features work reliably across all validated hosts:

• Canvas 2D / WebGL rendering
• Safe DOM manipulation (createElement, textContent, classList); sanitize any intentionally supported HTML
• CSS animations, transitions, custom properties, var(--host-variables)
• postMessage communication (MCP App bridge protocol)
• npm-bundled + vite-plugin-singlefile HTML output
• Server-proxied external data (server.ts fetches, returns via tool result)
• app.callServerTool() for UI→server communication
• app.updateModelContext() for UI→model communication

If your app stays within this set, it is compatible with the currently validated hosts under the recorded versions. Unknown hosts still require validation.