| Filename | Latest commit message | Latest commit date |
|---|---|---|
8a877b36b4* feat(examples): add debug-server example A comprehensive debug/development server for testing MCP Apps SDK features: - Vanilla TypeScript UI with collapsible panels - Message visualization (sent, received, errors) - Server tool calling interface - Multiple tool endpoints for testing * refactor(debug-server): convert to React - Replace vanilla TypeScript with React components - Add comprehensive Host Styles panel showing all CSS variables grouped by category - Use React hooks (useApp, useHostStyles, useAutoResize) - Cleaner state management with useReducer for event log - Collapsible sections for better organization - CSS modules for scoped styling * fix(debug-server): correct server name in main.ts * Revert "refactor(debug-server): convert to React" This reverts commit 5d22d2daa9a98ba412892447202ef10fbdb62f5b. * fix(debug-server): update default values for multipleBlocks and includeMeta * fix(debug-server): correct serve script and server name - serve script now runs main.ts instead of server.ts - Updated server name to 'Debug Server' - Fixed npx command in comment * fix: increase maxHeight to 6000px and add tools capability to debug app - basic-host: Increase maxHeight from 600 to 6000px - debug-server: Add tools capability to enable oncalltool/onlisttools handlers * fix(debug-server): use consistent callback names for event tracking Event types now match callback names (ontoolinput, ontoolresult, etc.) so the Callback Status panel shows correct counts and payloads. * feat(debug-server): add Update (Image) button for model context * feat(debug-server): add expandable event log entries - Click on any event log row to expand/collapse - Arrow indicator rotates when expanded - Full JSON payload shown indented in pre block - Max height with scroll for large payloads * style(debug-server): format long line in fullPayload function * test(debug-server): add to E2E tests and screenshot specs * chore: regenerate package-lock.json for cross-platform compatibility * update dep |
||
| .. | ||
| 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.