MCP Apps: generated typed client + shared bridge runtime from route contracts

[ScriptedAlchemy]

Problem

ScriptedAlchemy/cargo-hauler demonstrates that MCP App authors currently rebuild too much framework plumbing inside the browser bundle.

Its src/mcp/hauler/apps/dashboard.tsx manually owns:

• JSON-RPC request ids;
• window.parent.postMessage(..., '*');
• pending request bookkeeping and 15 s timeouts;
• tools/call request construction;
• result envelope unwrapping (structuredContent nested or direct);
• dozens of hand-written unknown interfaces for data already described by the route resultSchema;
• runtime shape readers to turn those hand-written interfaces back into typed dashboard models.

The corresponding tool already exports canonical inputSchema / resultSchema. The browser App cannot consume a generated, browser-safe typed client for that contract, so protocol and schema knowledge is duplicated across server and client.

This is exactly the seam #592 intends to remove: Apps should be views over the canonical application graph, not mini MCP clients.

Direction

Generate a browser-safe App client surface from Application IR / route contracts.

Illustrative author experience:

import { createAppClient } from 'agent-bundle/app';
import type { Routes } from 'agent-bundle/routes';

const client = createAppClient<Routes>();

const status = await client.tools.hauler.hauler_status({ limit: 40 });
const record = await client.tools.hauler.hauler_result({ ticket });

or generated helpers:

import { tools } from 'agent-bundle/routes/client';

await tools.hauler.hauler_status.call({ limit: 40 });

Exact API is open. Required properties are not.

Bridge runtime

The framework should own:

• request ids;
• request cancellation/timeouts;
• ui/* / tool-call bridge transport;
• result/error envelope decoding;
• origin/source validation appropriate to MCP Apps;
• host capability/consent errors;
• lifecycle/disposal;
• connection/rebind semantics used by Workbench, MCP hosts, serve-app, and First-class web surface (production): ship a browser host for the plugin's MCP Apps inside the artifact, openable from the installed CLI (<plugin> web); /web in dev for parity #564's production browser host.

Do not make each App use raw postMessage('*').

Types

The compiler already knows route input/output contracts. Emit browser-safe generated declarations from the same Application IR so importing types does not pull Zod or Node/runtime code into the App bundle.

For a route with resultSchema, client.call(...) should return the inferred structured result type directly or a typed result wrapper with an explicit .structured field. App code should not need to rediscover whether data is under structuredContent.

React integration

A thin optional React layer may provide query/subscription hooks, but the core client should not require React or Effect.

Examples:

const status = useTool('hauler/hauler_status', { limit: 40 }, {
  refetchInterval: 5_000,
});

This should reuse the same underlying client/runtime rather than introduce another transport implementation.

Relationship to #564

#564 should use this same browser bridge for standalone production hosting. Workbench preview, MCP-host embedded Apps, serve-app, and <plugin> web must not each grow different App client semantics.

Acceptance

• Generated browser-safe types expose tool input/output contracts without bundling server route modules or Zod.
• An App can call a known tool through a typed framework client without hand-writing JSON-RPC messages.
• Structured results are decoded consistently with the MCP projection.
• Error, timeout, cancellation, consent, and close/rebind behavior are framework-owned.
• Transport validates the expected parent/source/origin semantics rather than requiring app code to use unrestricted postMessage('*') directly.
• Workbench, serve-app, host embedding, and First-class web surface (production): ship a browser host for the plugin's MCP Apps inside the artifact, openable from the installed CLI (<plugin> web); /web in dev for parity #564's production browser host exercise the same core bridge contract.
• cargo-hauler can delete its local JSON-RPC client, PendingRequest, manual StructuredContent envelope plumbing, and the protocol-shape interfaces duplicated from its result schemas.

Consumer evidence

• ScriptedAlchemy/cargo-hauler/src/mcp/hauler/apps/dashboard.tsx
• ScriptedAlchemy/cargo-hauler/src/mcp/hauler/tools/hauler_status.tsx
• Meta-framework architecture: one application graph, capability-driven projections, one execution kernel #592
• First-class web surface (production): ship a browser host for the plugin's MCP Apps inside the artifact, openable from the installed CLI (<plugin> web); /web in dev for parity #564

[ScriptedAlchemy]

Implementation design — typed App client + App-side bridge runtime

I’m taking the browser App-side half of the shared bridge. This aligns with #564’s current design note: #564 owns/extracts the host-side McpAppFrameRelay, host page, HTTP routes, and artifact-resident process; #594 owns the code that runs inside an App and replaces hand-written window.parent.postMessage('*'), request ids, pending maps, and result readers.

Public surface

A browser-only agent-bundle/app entry will expose one transport/runtime and one typed client:

const client = createAppClient<AgentBundleAppRoutes>({
  appInfo: { name: 'cargo-hauler-dashboard', version: '1' },
});

await client.connect();
const status = await client.call('tool:mcp:hauler/hauler_status', { limit: 40 });
client.dispose();

call() returns the route’s inferred structured result directly. The MCP content, _meta, and isError envelope is transport/projection data; retaining it would force every view back onto structuredContent. A lower-level request() remains available for ui/* operations whose protocol result is itself the useful value.

The compiler-generated agent-bundle/routes/client module will bind route ids to protocol tool names and export a pre-typed factory/helpers. The runtime entry itself remains generic and browser-safe. The generated JS contains only the frozen id/name table plus an import of agent-bundle/app; route module/schema imports are type-only, so no Zod, Node built-ins, or server route modules enter the App chunk. Build tests will assert the emitted module graph/bytes, and the package declarations will pass check-declaration-imports --strict.

Naming will use the existing AgentBundleRoutes, RouteId, RouteInput, and RouteResult generated-contract vocabulary until #593 publishes a canonical replacement. If #593 adds a normalized RouteContract name before this lands, this generator will consume that shape rather than define a parallel IR.

Runtime contract

createAppBridge() / createAppClient() own:

• monotonic opaque request ids and collision-free pending bookkeeping;
• per-request timeout plus AbortSignal cancellation, with all pending requests rejected on rebind/dispose;
• ui/initialize / ui/notifications/initialized, tools/call, and typed ui/* requests;
• strict JSON-RPC response validation and CallToolResult decoding (structuredContent required for typed route calls; malformed/error tool results reject);
• one exported AppClientError class with a discriminated code (timeout, aborted, disposed, connection-rebound, invalid-message, rpc, capability-unavailable, consent-required, etc.);
• exact event.source and event.origin checks. connect() derives a non-opaque parent origin from document.referrer when possible; callers/hosts must provide targetOrigin when it cannot. No '*' send path exists;
• explicit lifecycle: connect(), idempotent dispose(), and rebind({ parent, targetOrigin }). Rebind removes the old listener, rejects old-generation requests, installs the new source/origin pair, and performs initialization again.

The default transport is DOM-shaped rather than tied to global window, so Workbench/serve-app/#564 tests and non-DOM unit tests instantiate the same core with injected window/parent ports.

Integration and proof

• The MCP App fixture will use generated agent-bundle/routes/client; no raw JSON-RPC remains in it.
• Unit coverage: envelope/result decoding, malformed responses, timeout, abort, consent/capability mapping, source/origin rejection, duplicate/late ids, rebind, and disposal.
• Existing Workbench and serve-app journeys will exercise this App client against the existing host bridge. First-class web surface (production): ship a browser host for the plugin's MCP Apps inside the artifact, openable from the installed CLI (<plugin> web); /web in dev for parity #564’s host page will consume the same wire contract and can import the shared types; it does not implement App-side ids/timeouts/decoding.
• cargo-hauler scratch migration will delete its PendingRequest, id generator, 15 s timer, wildcard postMessage, and structured-content readers; PR evidence will include before/after line counts and bundle graph proof.

I will reread #564 immediately before finalizing rebind() and stop if its implementation branch has committed a conflicting App-side bridge.

[ScriptedAlchemy]

Security correction after reading the production sandbox

The existing proxy renders the App in <iframe sandbox="allow-scripts" referrerpolicy="no-referrer" srcdoc=…>. The App document therefore has an opaque origin (event.origin === 'null' at the proxy) and no referrer from which it can discover the proxy origin. Requiring an exact targetOrigin for the first frame, as my design comment proposed, would not work in the real Workbench/serve-app path or portable MCP hosts.

The runtime will instead implement the safe bootstrap available to an opaque MCP App:

1. send only the framework-owned ui/initialize request with targetOrigin: '*';
2. accept its response only when event.source === configured parent, the JSON-RPC id matches the single bootstrap request, and the initialize result shape/protocol version is valid;
3. pin event.origin as the connection origin;
4. use that exact pinned origin for every subsequent request/notification, and reject every message from another source/origin;
5. clear the pin and all pending requests on explicit rebind/dispose.

Thus author code never calls wildcard postMessage; the one unavoidable wildcard is narrowly scoped inside the bridge handshake for the opaque-srcdoc environment. Hosts that can provide a trusted targetOrigin may skip wildcard bootstrap entirely.

[ScriptedAlchemy]

Consumer-audit addition

The cargo-hauler migration requires typed host notifications as part of the core API, not only call():

client.onToolInput((input) => { /* typed opening input */ });
client.onToolResult((result) => { /* typed opening structured result */ });
client.onToolCancelled((reason) => { /* terminal opening state */ });

Its dashboard currently uses the opening ui/notifications/tool-result as a pushed freshness baseline before polling. Omitting this would delete protocol plumbing but regress behavior. These listeners will use the same validated envelope decoder and lifecycle/rebind generation as requests; they do not introduce a second event transport.

Placement is confirmed as a browser-safe leaf agent-bundle/app, not @agent-bundle/runtime: route IR/typegen, MCP App compilation, serve-app, and the production host bridge are all owned by packages/agent-bundle, while the RSC runtime remains the Node/Flight execution package.

[ScriptedAlchemy]

Integrated implementation design (final before code)

Six focused audits are complete. This comment supersedes the illustrative route-id spelling and generated-value-module portions of the earlier note while retaining its App-side/host-side boundary and opaque-origin security correction.

Ownership

• MCP Apps: generated typed client + shared bridge runtime from route contracts #594: the App-inside-the-iframe runtime and typed client in a browser-safe agent-bundle/app leaf: initialization, ids, pending requests, timeout/abort, JSON-RPC/result decoding, typed opening notifications, errors, dispose/rebind, and source/origin pinning.
• First-class web surface (production): ship a browser host for the plugin's MCP Apps inside the artifact, openable from the installed CLI (<plugin> web); /web in dev for parity #564: the host-side McpAppFrameRelay, host page, HTTP routes, sandbox proxy, artifact process, and <plugin> web. MCP Apps: generated typed client + shared bridge runtime from route contracts #594 will not move or rewrite those modules.
• Existing createMcpAppBridge stays the host protocol implementation. Tests pair the new App client with it over injected ports, proving one wire contract rather than introducing another host bridge.

Generated typing and names

The current canonical type producer is .agent-bundle/routes.d.ts: it imports route modules type-only and infers inputSchema['_output'] / resultSchema['_output']. CompiledRouteGraph does not yet carry normalized result contracts, so #594 will extend this existing producer and remain compatible with #593 replacing its internals later.

The generated declaration will add exactly one augmentation:

declare module 'agent-bundle/app' {
  interface AppRegister {
    readonly routes: AgentBundleAppRouteContracts;
  }
}

AgentBundleAppRouteContracts contains only generated MCP tool routes. Runtime code never imports route modules or Zod; those imports remain type-only and are erased from App HTML. client.call('tool:hauler/hauler_status', input) returns that route's inferred object structured result directly.

Actual route IDs are tool:<server>/<name>; the previous tool:mcp:<server>/… example was wrong. Generated servers already derive the wire tool name from the final id segment and have no name override. #594 will centralize that zero-dependency helper and rewire current callers in the same change, then reuse it in the App client. A generated agent-bundle/routes/client runtime table is intentionally omitted: it would duplicate derivable information and require a second virtual-module path before #593 establishes richer IR. The generated typed client requirement is satisfied by the generated AppRegister contract consumed by createAppClient().

Public API

import { createAppClient } from 'agent-bundle/app';

const client = createAppClient({
  appInfo: { name: 'hauler-dashboard', version: '1' },
  timeoutMs: 15_000,
});

await client.connect();
const status = await client.call('tool:hauler/hauler_status', { limit: 40 });
client.onToolResult('tool:hauler/hauler_status', (opening) => { /* typed */ });
client.onToolInput('tool:hauler/hauler_status', (opening) => { /* typed */ });
client.onToolCancelled((reason) => { /* terminal */ });
client.dispose();

request() remains the lower-level typed JSON-RPC escape hatch for resources/read and supported ui/* methods. One AppClientError class carries a discriminated code: timeout, aborted, disposed, connection-rebound, invalid-message, rpc, capability-unavailable, or consent-required. RPC -32601 maps to capability, -32001 to consent, and other operation failures to rpc.

call() returns structured data directly and rejects isError, missing structured data, or malformed envelopes. This deliberately supports object-rooted route result contracts, matching the generated MCP projection: scalar/array results do not produce structuredContent and are not exposed as typed App calls.

Opaque sandbox handshake

The real App is a no-referrer opaque srcdoc; it cannot know its proxy origin. The runtime therefore sends only its framework-owned ui/initialize bootstrap to '*', accepts a response only from the exact configured parent with the matching bootstrap id and valid protocol shape, pins that response origin, then uses and accepts only the pinned origin. A trusted targetOrigin option skips wildcard bootstrap. Rebind/dispose remove listeners, clear the pin, and reject the old generation's pending requests.

Proof

• Unit: handshake/pinning, malformed/duplicate/late envelopes, structured decoding, timeout, abort, consent/capability mapping, typed notifications, rebind, dispose, and a paired createMcpAppBridge journey.
• Typegen: one agent-bundle/app augmentation, MCP tools only, real TS program proof, generated input/result inference.
• Bundle/declarations: App HTML import graph contains no Zod, Node, Effect, or server route module at runtime; self-contained inline build remains unchanged; dist/app.d.ts passes check-declaration-imports --strict.
• Product surfaces: migrate the public MCP App example from @modelcontextprotocol/ext-apps; existing browser-app, Workbench, and serve-app journeys then exercise the same client against the existing host bridge.
• cargo-hauler scratch proof: remove the 411-line transport/type/reader spans where canonical route results replace them, preserving domain compatibility logic; record before/after counts and cross-reference cargo-hauler meta-framework: execution plan and sequencing #107 §3.

No new AB diagnostic is planned: browser failures are AppClientError codes. Existing AB4837 docs will list agent-bundle/app as bundle-safe. This is additive, so the changeset is patch for agent-bundle only.

[ScriptedAlchemy]

Implemented and squash-merged in PR #601 at 0d4a37cef764e54acd93b9d6eb780fa61e5e02eb. The typed agent-bundle/app client, shared host-bridge cancellation/route validation, canonical generated contracts, browser/Workbench/serve-app proofs, bilingual docs, and cargo-hauler dry-run are included. This closes the framework prerequisite for cargo-hauler #107 §3.