openwork/docs/features/remote-mcp-apps/demo-runbook.md

Native MCP Apps local demo

This runbook proves the native MCP Apps path with a deterministic local fixture. It does not depend on a hosted gallery, production rollout flags, customer connectors, or personal credentials.

The required fixture is Project Atlas from evals/specs/remote-mcp-apps.e2e.test.ts. It runs as a local Streamable HTTP MCP server, exposes ui://project-atlas/view.html, and has a same-server search_projects operation. The tape starts real local Den API and Web processes, a real Electron Desktop/local-server process, MySQL, Redis, and a synthetic model server.

Prerequisites

• Node.js 24 and pnpm 11.4.0 (the versions declared by the repository)
• Bun, Docker, and an available local MySQL port (3306)
• no real model/provider credentials in the shell

From a clean checkout of the exact branch under test:

pnpm install --frozen-lockfile
pnpm --dir evals install --frozen-lockfile
pnpm --filter @openwork/types build
pnpm --filter @openwork-ee/den-db build
pnpm --filter @openwork/email build
pnpm dev:den:mysql

Run the exact-head demo tape

OPENWORK_EVAL_E2E_TESTS=1 pnpm evals:e2e remote-mcp-apps

A valid required proof ends with one passing test, zero failed tests, zero skips, and "verdict":"passed". Keep the JSON report path printed by the runner with the local verification record.

The tape performs this demo sequence:

1. Starts an isolated Den organization, synthetic member, local Project Atlas MCP server, and Desktop profile.
2. Adds Project Atlas as an organization Connect MCP server and waits for it to become ready.
3. Confirms the model-visible surface contains only the central search_capabilities and execute_capability tools.
4. Confirms stale per-connection compatibility exposes only that same bounded pair, no resources/templates/App metadata, and no direct provider tools.
5. Confirms the private App host receives only the originating server's app-visible tools and exact ui://project-atlas/view.html resource.
6. Searches and executes search_projects through the originating server's App-host capability pair and observes the synthetic Atlas migration result.
7. Prompts the synthetic model to return the bound tool result, renders the App in Desktop, reloads it, and confirms it renders again.
8. Restarts Desktop with the same isolated profile, revisits the session, and confirms the App recovers.

Native MCP Apps are enabled for every deployment and organization; no deployment or organization gate needs to be flipped for this demo.

Focused security and compatibility checks

cd apps/server
bun --conditions=development test \
  src/connect-mcp-server-catalog.test.ts \
  src/mcp-app-host.test.ts \
  src/mcp-app-sandbox.test.ts \
  src/cloud-mcp-reconcile.e2e.test.ts

cd ../app
bun test \
  tests/den-mcp-url.test.ts \
  tests/mcp-app-frame.test.ts \
  tests/session-mcp-maintenance.test.ts \
  tests/cloud-mcp-maintenance-gate.test.ts

cd ../../ee/apps/den-api
bun test \
  test/remote-mcp-app-rollout.test.ts \
  test/external-connection-proxy.test.ts \
  test/admin-organization-capabilities.test.ts \
  test/organization-capabilities.test.ts

These checks cover exact trusted-origin matching, cross-origin rejection, origin-bound App-host credentials, App-host credential privacy, sandbox/CSP enforcement, same-server binding, rollout defaults, older responses without an App-host credential, bounded stale-client compatibility, and preservation of ordinary Connect when Apps are disabled.

Expected failure categories

• A skipped tape is incomplete proof. Check the consent environment variable, local placement, and MySQL availability.
• missing local server credentials is a Desktop startup/readiness problem.
• A resource error names the exact URI, MIME, size, or CSP validation failure.
• An origin error indicates that the Den/App-host endpoint pair is not an exact trusted-origin match.
• A tool denial indicates wrong-server routing, app visibility, workspace policy, provider authorization, or required mutation confirmation.
• A client that does not advertise the private App-host capability keeps the bounded search/execute surface; that is expected, not a resource-loading failure.

The hosted SOL gallery may be checked separately as an external observation, but its reachability is not OpenWork compatibility proof and it is not part of this required demo.