| Filename | Latest commit message | Latest commit date |
|---|---|---|
e479497371* fix(e2e): add masks for dynamic content and increase timeouts for slow servers - Add HOST_MASKS for Tool Input/Result panels with dynamic timestamps - Add say-server to SLOW_SERVERS (10s) for TTS model download - Add say-server to EXTRA_WAIT_MS (30s) in generate-grid-screenshots * feat: add update-lock:docker script to regenerate lockfile with public registry * pin package versions for dev compatibility * feat(basic-host): add ?theme=hide query param to hide theme toggle in screenshots - Add hideThemeToggle param to getQueryParams() - Conditionally render ThemeToggle based on ?theme=hide - Update e2e tests to use ?theme=hide for consistent screenshots * update screenshots * update screenshots * fix(husky): load Node.js environment for GUI apps like GitHub Desktop * fix(e2e): increase map-server wait time to 15s for tile loading * fix(e2e): increase waitForAppLoad timeout to 30s for nested iframe loading * ci: add workflow to update e2e snapshots * ci: trigger snapshot update on push to this branch * chore: update e2e snapshots [skip ci] * ci: trigger CI after snapshot update * style: fix prettier formatting in update-snapshots workflow * fix: pin seroval, seroval-plugins, and solid-js for artifactory compatibility --------- Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> |
||
| .. | ||
| src | ||
| .gitignore | ||
| index.html | ||
| package.json | ||
| README.md | ||
| sandbox.html | ||
| serve.ts | ||
| tsconfig.json | ||
| vite.config.ts | ||
Example: Basic Host
A reference implementation showing how to build an MCP host application that connects to MCP servers and renders tool UIs in a secure sandbox.
This basic host can also be used to test MCP Apps during local development.
Key Files
index.html/src/index.tsx- React UI host with tool selection, parameter input, and iframe managementsandbox.html/src/sandbox.ts- Outer iframe proxy with security validation and bidirectional message relaysrc/implementation.ts- Core logic: server connection, tool calling, and AppBridge setup
Getting Started
npm install
npm run start
# Open http://localhost:8080
By default, the host application will try to connect to an MCP server at http://localhost:3001/mcp. You can configure this behavior by setting the SERVERS environment variable with a JSON array of server URLs:
SERVERS='["http://localhost:1234/mcp", "http://localhost:5678/mcp"]' npm run start
Architecture
This example uses a double-iframe sandbox pattern for secure UI isolation:
Host (port 8080)
└── Outer iframe (port 8081) - sandbox proxy
└── Inner iframe (srcdoc) - untrusted tool UI
Why two iframes?
- The outer iframe runs on a separate origin (port 8081) preventing direct access to the host
- The inner iframe receives HTML via
srcdocand is restricted by sandbox attributes - Messages flow through the outer iframe which validates and relays them bidirectionally
This architecture ensures that even if tool UI code is malicious, it cannot access the host application's DOM, cookies, or JavaScript context.