dsh-mcp-apps
MCP Apps support for DeepSeek Harness (DSH), packaged as ordinary Cordis plugins.
The project deliberately keeps the protocol host and each presentation surface separate. Installing the bundle adds two independent rows: a Host service that shares the existing MCP connection and a Web renderer that runs App HTML behind a double-iframe sandbox. One AppBridge session can move between inline, fullscreen, and picture-in-picture surfaces without remounting its iframe.
Which package should I install?
| Goal | Install |
|---|
| Use Codex, Claude Code, Pi, or portable Agent Plugins in DSH, including their MCP Apps | @openma/dsh-agents-plugins-bridge only; it already carries MCP Apps |
| Add MCP Apps to a Web profile without the foreign-plugin bridge | @openma/dsh-mcp-apps |
The standalone package and the Bridge use the same Host and Web runtime
packages. Do not install both bundles into one profile just to get the
renderer twice.
Install
dsh plugin --profile web add @openma/dsh-mcp-apps
From a local checkout, install dependencies and add only the root bundle:
npm install
dsh plugin --profile web add .
The full bundle is safe on a DSH composition that already provides ctx.mcpApps
and the generated remote.mcpApps namespace: the fallback Host row becomes a
no-op and the Web renderer reuses the existing Remote. If the active profile is
known to include the official Host already, installing only the renderer is the
minimal equivalent:
dsh plugin --profile web add ./packages/web
The renderer consumes a composition-provided Remote when present and mounts its
checked-in descriptor only for the standalone fallback Host.
The bundle patch mounts one kernel:
- id: mcp-apps-bundle
name: '@openma/dsh-mcp-apps'
That kernel owns two independent child rows, mcp-apps-host and
mcp-apps-web. Both rows point at package-owned wrapper exports. Each wrapper
resolves its runtime from this package's dependency graph, imports it through
the DSH Loader, and mounts it with ctx.plugin; profile-level dependency
hoisting is not required. The Agent Plugins Bridge uses the same wrapper shape
from its own root package.
Keep MCP server connections as their own plugin rows. DSH's mcp-client notices the optional ctx.mcpApps service and contributes its live connection automatically:
- name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: weather
transport: stdio
command: weather-mcp-server
Tools, resources, prompts, model-facing execution, and AppBridge calls therefore reuse one MCP SDK Client, including its authentication and reconnect generation. This project does not open a second connection.
Packages
| Package | Role |
|---|
@openma/dsh-mcp-apps | Installable and nestable bundle kernel; owns the Host/Web child-row lifecycle |
@openma/dsh-mcp-apps-host | Internal runtime package: ctx.mcpApps provider registry plus the generated Typert Host/Remote contract |
@openma/dsh-mcp-apps-web | Internal runtime package: shape-driven Tool-result renderer, official AppBridge, and browser sandbox |
The flow is:
dsh mcp-client
└─ provider → @openma/dsh-mcp-apps-host
└─ Typert Remote → @openma/dsh-mcp-apps-web
└─ AppBridge → sandboxed MCP App
Only callTool and readResource cross the browser Remote boundary. readResource accepts only ui:// URIs. Host plugins may also call listResources, listPrompts, and getPrompt in process; this package does not inject those results into model context.
The Web renderer claims only settled results with all of the following:
- presentation card
mcp-app;
- a
ui:// resource URI;
- exact MIME type
text/html;profile=mcp-app;
- a schema-valid MCP Tool result.
Every other result declines the tool.call.takeover chain, leaving the normal keyed Tool view and generic fallback intact.
Browser security boundary
Untrusted App HTML never runs in the DSH document. It is loaded into an opaque-origin inner data document behind an opaque-origin relay document. The renderer:
- installs CSP before App code, accepting only validated HTTP(S)/WS(S) domain sources;
- checks exact parent/child windows and expected origins on every relay message;
- reserves internal sandbox messages and uses a per-document generation marker;
- closes Host-to-App forwarding as soon as the inner document navigates;
- allows external navigation only to HTTP(S) URLs in a new tab;
- bounds inline height requests to 96–720 px;
- moves one live iframe wrapper between inline, a right-side panel for the
protocol's
fullscreen mode, and bounded picture-in-picture instead of
recreating App state;
- exposes unobtrusive bottom-left Host controls only for display modes the App
advertises through
appCapabilities.availableDisplayModes.
The implementation uses the official @modelcontextprotocol/ext-apps AppBridge and PostMessageTransport.
Other clients
The Host package is UI-neutral. The full HTML/AppBridge path is currently implemented only by the Web package. A TUI can install the Host independently and provide its own renderer (for example, a text fallback or “open in browser” action); terminal clients should not execute arbitrary App HTML inline.
@openma/dsh-agents-plugins-bridge
uses this boundary directly: its Web profile gets the sandboxed renderer, while
its TUI profile keeps the shared MCP tools, resources, prompts, and backend
lifecycle without attempting to draw App HTML in the terminal.
Related projects
Development
Node.js 20 or newer is required.
npm install
npm run build
npm test
npm run typecheck
npm run test:browser
test:browser launches Playwright Chromium (or local Google Chrome on macOS) to verify the double-iframe origin and navigation boundary.
examples/display-modes is a real stdio MCP
server built with the official MCP Apps server helpers and App client. Its
display_modes tool opens ui://dsh/display-modes; increment the counter and
switch through all three surfaces to verify that the App session remains live:
npm run build:example:display-modes
node examples/display-modes/server.mjs
Compatibility
The Web renderer targets the tool.call.takeover chain present in current DSH
Web builds. When composed with DSH 0.1.0-rc.7, its priority -110 lets this
three-mode renderer claim an MCP App result before the bundled inline-only
renderer at priority -100. Other tool results continue down the ordinary
takeover chain.
Downloads, App-to-chat messages, and sampling are not enabled yet.
License
MIT
