spec: Add tool registration for Apps, to be called by Host (WebMCP-style!)

[ochafik]

Summary

This PR enables Apps to register their own tools that agents can call, making apps introspectable and accessible to the model.

Apps expose semantic interfaces (state queries, operations) via standard MCP tools. The agent discovers capabilities via tools/list, queries state, and drives interactions. This is pull-based and complements the existing push channel (ui/update-model-context): push lets the app proactively update the model's context, pull lets the agent query and command the app on demand. Apps may use either or both.

Example:

// Agent can query structured state
app.registerTool("get_board_state", {
  outputSchema: z.object({
    board: z.array(z.enum(['X', 'O', null])),
    currentPlayer: z.enum(['X', 'O']),
    winner: z.enum(['X', 'O', 'draw', null]).nullable()
  })
}, async () => ({
  structuredContent: { board, currentPlayer, winner: checkWinner(board) }
}));

// Agent can execute actions
app.registerTool("make_move", {
  inputSchema: z.object({ position: z.number().int().min(0).max(8) })
}, async ({ position }) => {
  board[position] = currentPlayer;
  currentPlayer = currentPlayer === 'X' ? 'O' : 'X';
  return { structuredContent: { board, winner: checkWinner(board) } };
});

Agent interaction:

// Discover → Query → Act
const { tools } = await bridge.sendListTools({});
const state = await bridge.sendCallTool({ name: "get_board_state" });
await bridge.sendCallTool({ name: "make_move", arguments: { position: 4 } });

Changes

App side (app.ts)

• registerTool() - Register tools with Standard Schema validation (Zod, ArkType, Valibot, …)
• oncalltool / onlisttools - Handle tool requests
• sendToolListChanged() - Notify on tool updates
• Tools support enable(), disable(), update(), remove()

Host side (app-bridge.ts)

• sendCallTool() - Call app tools
• sendListTools() - List app tools
• Fix: Use correct ListToolsResultSchema

Capabilities (types.ts)

• Apps: tools: { listChanged?: boolean }
• Hosts: serverTools: { listChanged?: boolean } (existing)

Tests: ✓ 27 passing, 100% coverage

Design

Reuses standard MCP messages: tools/call, tools/list, notifications/tools/list_changed

Similar to WebMCP but without turning the App (embedded page) into an MCP server - apps register tools within the App/Host architecture.

Lifecycle: App tools exist only while app loaded (ephemeral, sandboxed)

Separation: Server tools (persistent, trusted) vs App tools (ephemeral, sandboxed)

Review feedback addressed

Schema validation — Standard Schema

App.registerTool accepts any Standard Schema implementation (Zod, ArkType, Valibot, …) — aligned with typescript-sdk#1689. zod is now an optional peer; there is no static zod import in src/app.ts.

Compat: zod v3.25.x lacks ~standard.jsonSchema, so serialization falls back to a lazy z.toJSONSchema when vendor==='zod'. The full ^3.25.0 || ^4.0.0 peer range is preserved.

Long-running app tools

App tools/call may be task-augmented per core MCP Tasks. Hosts proxy tasks/* to the app like they proxy tools/call; apps SHOULD delegate long-lived work to the server so the task survives iframe teardown.

Spec clarifications

• Tool registration framed as pull, complementing the existing push ui/update-model-context (feat: add ui/update-model-context #125 landed after this PR was opened).
• Host has no guaranteed DOM access into apps (cross-origin frameDomains); the tool surface is the only reliable introspection path.
• Tool structure now lists title/outputSchema/_meta and links to the core MCP Tool type. SDK no longer emits an empty outputSchema when none was declared.

Breaking Changes

None. Purely additive.

Related

Implements the gist of #35 (WebMCP-style tool registration) while preserving the App/Host architecture.

🤖 Generated with Claude Code

[pkg-pr-new]

Open in StackBlitz

@modelcontextprotocol/ext-apps

npm i https://pkg.pr.new/@modelcontextprotocol/ext-apps@72

@modelcontextprotocol/server-basic-preact

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-preact@72

@modelcontextprotocol/server-basic-react

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-react@72

@modelcontextprotocol/server-basic-solid

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-solid@72

@modelcontextprotocol/server-basic-svelte

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-svelte@72

@modelcontextprotocol/server-basic-vanillajs

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-vanillajs@72

@modelcontextprotocol/server-basic-vue

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-vue@72

@modelcontextprotocol/server-budget-allocator

npm i https://pkg.pr.new/@modelcontextprotocol/server-budget-allocator@72

@modelcontextprotocol/server-cohort-heatmap

npm i https://pkg.pr.new/@modelcontextprotocol/server-cohort-heatmap@72

@modelcontextprotocol/server-customer-segmentation

npm i https://pkg.pr.new/@modelcontextprotocol/server-customer-segmentation@72

@modelcontextprotocol/server-debug

npm i https://pkg.pr.new/@modelcontextprotocol/server-debug@72

@modelcontextprotocol/server-map

npm i https://pkg.pr.new/@modelcontextprotocol/server-map@72

@modelcontextprotocol/server-pdf

npm i https://pkg.pr.new/@modelcontextprotocol/server-pdf@72

@modelcontextprotocol/server-scenario-modeler

npm i https://pkg.pr.new/@modelcontextprotocol/server-scenario-modeler@72

@modelcontextprotocol/server-shadertoy

npm i https://pkg.pr.new/@modelcontextprotocol/server-shadertoy@72

@modelcontextprotocol/server-sheet-music

npm i https://pkg.pr.new/@modelcontextprotocol/server-sheet-music@72

@modelcontextprotocol/server-system-monitor

npm i https://pkg.pr.new/@modelcontextprotocol/server-system-monitor@72

@modelcontextprotocol/server-threejs

npm i https://pkg.pr.new/@modelcontextprotocol/server-threejs@72

@modelcontextprotocol/server-transcript

npm i https://pkg.pr.new/@modelcontextprotocol/server-transcript@72

@modelcontextprotocol/server-video-resource

npm i https://pkg.pr.new/@modelcontextprotocol/server-video-resource@72

@modelcontextprotocol/server-wiki-explorer

npm i https://pkg.pr.new/@modelcontextprotocol/server-wiki-explorer@72

commit: 5f6dec0

[connor4312]

How should it would if I'm in a chat and have multiple MCP apps currently visible, and they register the same tool? Does the host send tool calls to most recent one? (If so is there a way to signal to the older app that it can no longer receive tool calls?)

I think I'm also not clear on the lifetime of apps. Currently in the spec there is no specific bounds on the lifetime of the MCP apps. For VS Code, we implement virtualization and so an app is not loaded if the user has it scrolled out of the viewport. But now we need to actively keep app apps alive for some amount of time (forever?) in case a model decides to later call them. For long chat sessions this could get quite expensive.

I think #125 is a simpler approach that should cover the bases here without introducing lifetime concerns

[github-actions]

📖 Docs Preview Deployed

Preview (stable)	https://pr-72.mcp-ext-apps-docs-preview.pages.dev
This commit	https://5d3598f9.mcp-ext-apps-docs-preview.pages.dev
Commit	dcfc95c

Includes drafts and future-dated posts. All pages served with noindex, nofollow — search engines will not crawl this preview.

[connor4312]

For native mobile sdks we'll definitely need to accept death of scrolled-out apps as inevitable.
Widget state persistence / restoration can be one way to handle this gracefully, but we'll ideally need new protocol support for this (currently the workaround is to use localStorage indexed by hostInfo.toolInfo.id)

@ the MCP summit, there is a talk from an engineer who mentions using MCP Apps as a way to deliver state updates (triggering async sendMessage or updateModelContext). I think we could definitely use some API for an app to request to be pinned or not virtualized because it's actively providing context. I feel like I would not want this to be implicit for whether the model provides tools or not, because it feels a bit heavy to need to register or unregister all my tools to signal this. Something like app.persist(AbortSignal) -- could workshop it 😄

[antonpk1]

big fan of this feature!