Add MCP Apps support to Inspector

[cliffhall]

Summary

Implements complete MCP Apps support in the Inspector, enabling detection, listing, and interactive rendering of MCP apps with full bidirectional communication.

Implementation

New Components:

• AppsTab - Detects and displays tools with _meta.ui.resourceUri field
• AppRenderer - Handles full MCP App lifecycle with AppBridge integration

Files Added:

• client/src/components/AppsTab.tsx
• client/src/components/AppRenderer.tsx
• client/src/components/__tests__/AppsTab.test.tsx
• client/src/components/__tests__/AppRenderer.test.tsx
• server/static/sandbox_proxy.html - sandbox proxy similar to In sandbox_proxy.html
  • refactor to match basic-host example, creates an nested iframe for security. In this implementation, for simplicity the sandbox.ts is inlined in sandbox_proxy.html as javascript example. Served on a different port via the proxy server.

Files Modified:

• client/src/App.tsx - Added Apps tab integration, auto-fetch logic, and resource wiring
• client/src/components/ListPane.tsx - Only show Clear button if a clearItems function was passed in
• client/src/components/__tests__/ListPane.test.tsx - Make sure Clear button is not shown if no clearItems function was passed in
• client/src/components/__tests__/AuthDebugger.test.tsx - Fix @ imports that were not resolving to be relative
• client/package.json - Added @modelcontextprotocol/ext-apps^1.0.0, @mcp-ui/client^6.0.0 dependencies
• client/jest.config.cjs - Updated to handle ES modules from @modelcontextprotocol/ext-apps
• server/src/index.ts - add /sandbox endpoint which reads and serves static/sandbox_proxy.html with no-cache header and rate limiting
• server/package.json - Added shx^0.3.4 and express-rate-limit:^8.2.1 dependencies. Copy static folder to build in build script.

Key Features

✅ App Detection - Automatically identifies tools with MCP Apps extension metadata
✅ Auto-population - Apps list loads when Apps tab becomes active
✅ Resource Fetching - Fetches ui:// resources via MCP protocol
✅ MCP-UI AppRenderer Integration - Renders the app, given an MCP client, tool name, resource content, and host context (custom settings like theme)
✅ PostMessage Transport - Secure JSON-RPC communication between iframe and host
✅ Sandboxed Rendering - Secure iframe rendering with configurable permissions
✅ Theme Support - Passes Inspector's light/dark theme to apps
✅ Error Handling - Comprehensive error states and user feedback

Architecture

┌─────────────────────────────────────────────────────────┐
│                      Inspector Host                     │
│  ┌──────────────┐    ┌────────────┐   ┌──────────────┐  │
│  │   AppsTab    │───→│ AppRenderer│───│   MCP Client │  │
│  └──────────────┘    └────────────┘   └──────────────┘  │
│                            │                 │          │
│                            ↓                 ↓          │
│                      ┌────────────┐    ┌────────────┐   │
│                      │ AppBridge  │←───│ MCP Server │   │
│                      └────────────┘    └────────────┘   │
│                            │                            │
│                            ↓                            │
│                   ┌─────────────────┐                   │
│                   │ PostMessage     │                   │
│                   │ Transport       │                   │
│                   └─────────────────┘                   │
│                            │                            │
└────────────────────────────┼────────────────────────────┘
                             ↓
                    ┌─────────────────┐
                    │  Sandboxed      │
                    │  iframe         │
                    │  (MCP App UI)   │
                    └─────────────────┘

Test Coverage

AppsTab Tests (18 tests):

• App detection and filtering
• Grid display of multiple apps
• Refresh functionality
• Error handling
• App selection and deselection
• Dynamic tool list updates
• Resource content handling

AppRenderer Tests (8 tests):

• Loading states
• Resource fetching logic
• Error states
• Iframe rendering with proper attributes
• AppBridge initialization and connection
• JSON and HTML content parsing
• Custom permissions handling
• Component lifecycle

All 477 tests pass successfully

Quality Checks

• ✅ Prettier formatting applied
• ✅ ESLint passing with no errors
• ✅ All tests passing (477/477)
• ✅ Build successful

Closes #1041

Videos

Map Server

map.mov

Cohort Heatmap Server

cohort.mov

Wiki Explorer Server - Navigation

wiki.mov

Wiki Explorer Server - Open Links

wiki-open-link.mov

---

Generated with Claude Code
Fixed with Junie and plenty of old-school hacking.

[olaservo]

Added a few suggestions.

I'm still testing with a few more servers too, since I still can't tell if some weirdness is due to the servers or the inspector yet. For example, some servers are rendering with a black background (this one) or just render a black rectangle for me (like this one). So far I think its the servers that need some adjustment?

It also looks like there are a lot of console.log statements, so I wasn't sure if we should keep all those as-is or if they were meant to be more temporary?

[cliffhall]

For example, some servers are rendering with a black background (this one)

@olaservo that's the cohort-heatmap-server, which was working for me in the screenshot and video above. I'm using Chrome on macOS. You?

just render a black rectangle for me (like this one). So far I think its the servers that need some adjustment?

I get the app rendering, and the scaling buttons are present, but it doesn't seem to load the data. When I run it in the ext-apps browser demo, I see the content...

It also looks like there are a lot of console.log statements, so I wasn't sure if we should keep all those as-is or if they were meant to be more temporary?

I sort of thought they might be useful for a time, until we are certain everything is working properly. I can take them out.

[olaservo]

For example, some servers are rendering with a black background (this one)

@olaservo that's the cohort-heatmap-server, which was working for me in the screenshot and video above. I'm using Chrome on macOS. You?

@cliffhall I'm using Chrome on Windows and have a dark system theme on, so I think that's why the heatmap hows with a dark theme. Otherwise I think that one is actually ok since the source code for that server seems to prefer the system theme.

I sort of thought they might be useful for a time, until we are certain everything is working properly. I can take them out.

Sure that makes sense!

[infoxicator]

@cliffhall did you try the React Renderer for hosts? It should be plug and play and has most of the spec implementations needed by hosts etc. It is what I have been using at Postman (soon to be used by MCPJam and Goose)

Let me know if you want to take a look https://github.com/MCP-UI-Org/mcp-ui/blob/main/sdks/typescript/client/src/components/AppRenderer.tsx

it is released on the latest version of the mcp-ui package so you can just npm install it

[cliffhall]

Quick update

• I've refactored to use the mcp-ui AppRenderer and added a tool input form. It works much better now (see new videos at the top), but some example servers still don't seem to work, not certain why. e.g., budget-allocator-server takes no input but still doesn't render any data, though its UI is rendered.

• I still need to figure out how / whether to implement the nested iframe model that the basic-host example uses, but with React and mcp-ui. Should I put an iframe around the mcp-ui AppRenderer instance? Shouldn't that be part of AppRenderer itself? Is it a required pattern?

• Code QL is complaining about XSS threats in the sandbox_proxy.html file. Above here, here, and here, I had applied co-pilot's suggestions for sanitization, but it stopped the apps from rendering altogether, and I've since removed them. I need to understand what the best practice is for that sandbox html and if the nested iframe model mentioned above fixes the problem.

[infoxicator]

@cliffhall I think the only thing missing is wiring the callbacks for the actions. Here's what we need to pass:

// log the ui event and open the link in a new tab
onOpenLink={async ({ url }) => {
if (url.startsWith('https://') || url.startsWith('http://')) {
window.open(url);
}
}}
// log the UI event (maybe logging it somehwere in the inspector so the message is visible and acknowledged?
onMessage={async (params) => {
console.log('Message from tool UI:', params);
return { isError: false };
}}

/** Handler for logging messages from the guest UI */
// this one should be sent to the inspector's notifications list
onLoggingMessage?: (params: LoggingMessageNotification['params']) => void;

You can test all this functionality with the ext-apps/react-server demo that has the get time to test tool calling, the send message, send notification etc.

[cliffhall]

WIP. Added onOpenLink handler. Adding video to PR.

[cliffhall]

Added support for showing handling McpUiMessageRequest messages and showing them as toasts.

[cliffhall]

Still need to handle logging messages