modelcontextprotocol/ext-apps
Watch
1
0
Fork
You've already forked ext-apps
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

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

Browse source 
* feat: Add tool registration and bidirectional tool support

This PR adds comprehensive tool support for MCP Apps, enabling apps
to register their own tools and handle tool calls from the host.

- Add `registerTool()` method for registering tools with input/output schemas
- Add `oncalltool` setter for handling tool call requests from host
- Add `onlisttools` setter for handling tool list requests from host
- Add `sendToolListChanged()` for notifying host of tool updates
- Registered tools support enable/disable/update/remove operations

- Add `sendCallTool()` method for calling tools on the app
- Add `sendListTools()` method for listing available app tools
- Fix: Use correct ListToolsResultSchema (was ListToolsRequestSchema)

- Add comprehensive tests for tool registration lifecycle
- Add tests for input/output schema validation
- Add tests for bidirectional tool call communication
- Add tests for tool list change notifications
- All 27 tests passing

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* nits

* Update apps.mdx

* feat: Add automatic request handlers for app tool registration

Implement automatic `oncalltool` and `onlisttools` handlers that are
initialized when apps register tools. This removes the need for manual
handler setup and ensures tools work seamlessly out of the box.

- Add automatic `oncalltool` handler that routes calls to registered tools
- Add automatic `onlisttools` handler that returns full Tool objects with JSON schemas
- Convert Zod schemas to MCP-compliant JSON Schema using `zod-to-json-schema`
- Add 27 comprehensive tests covering automatic handlers and tool lifecycle
- Test coverage includes error handling, schema validation, and multi-app isolation

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* type updates

* fix: Ensure tools/list returns valid JSON Schema for all tools

- Always return inputSchema as object (never undefined)
- Keep filter for enabled tools only in list
- Update test to match behavior (only enabled tools in list)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* type updates

* rm zod-to-json-schema

* fix: Update RegisteredTool to use 'handler' instead of 'callback' (SDK API change)

* refactor: Rename sendCallTool/sendListTools to callTool/listTools

Avoid double-verb naming pattern for consistency with existing API.

* feat: Add screenshot and click support to SDK

- Add McpUiScreenshotRequest/Result and McpUiClickRequest/Result types
- Add onscreenshot and onclick handlers to App class
- Add screenshot() and click() methods to AppBridge class
- Generate updated Zod schemas

* feat(map-server): Enable registerTool with navigate-to and get-current-view

- Uncomment and fix the navigate-to tool for animated navigation
- Add get-current-view tool to query camera position and bounding box
- Add flyToBoundingBox function for smooth camera animation
- Add setLabel function for displaying location labels

* feat(pdf-server): Add widget interaction tools

- get-document-info: Get title, current page, total pages, zoom level
- go-to-page: Navigate to a specific page
- get-page-text: Extract text from a page
- search-text: Search for text across the document
- set-zoom: Adjust zoom level

* feat(shadertoy-server): Add widget interaction tools

* feat(examples): Add widget interaction tools to budget-allocator, shadertoy, wiki-explorer, and threejs

budget-allocator:
- get-allocations: Get current budget allocations
- set-allocation: Set allocation for a category
- set-total-budget: Adjust total budget
- set-company-stage: Change stage for benchmarks
- get-benchmark-comparison: Compare against benchmarks

shadertoy:
- set-shader-source: Update shader source code
- get-shader-info: Get shader source and compilation status
- Sends errors via updateModelContext

wiki-explorer:
- search-article: Search for Wikipedia articles
- get-current-article: Get current article info
- highlight-node: Highlight a graph node
- get-visible-nodes: List visible nodes

threejs:
- set-scene-source: Update the Three.js scene source code
- get-scene-info: Get current scene state and any errors
- Sends syntax errors to model via updateModelContext

* feat: Add expand-node tool to wiki-explorer and update tool descriptions

Wiki Explorer:
- Add expand-node tool - the critical missing tool for graph exploration
- Claude can now programmatically expand nodes to discover linked articles

Server descriptions updated to mention widget tools:
- map-server: navigate-to, get-current-view
- pdf-server: go-to-page, get-page-text, search-text, set-zoom, get-document-info
- budget-allocator: get-allocations, set-allocation, set-total-budget, etc.
- shadertoy: set-shader-source, get-shader-info
- wiki-explorer: expand-node, search-article, highlight-node, etc.

All descriptions now mention 'Use list_widget_tools to discover available actions.'

* refactor: Simplify tool descriptions - remove client implementation details

The server tool descriptions now just mention that widgets are interactive
and can be controlled, without teaching the model about list_widget_tools
(which is the client's responsibility to teach).

Before: 'The widget exposes tools: X, Y, Z. Use list_widget_tools to discover...'
After:  'The widget is interactive and exposes tools for X and Y.'

* Remove ui/screenshot and ui/click protocol methods

These will be proposed separately from the app tool registration changes.

* fix(app): auto-register tools capability in registerTool

When registerTool is called before connect() on an App created without
explicit tools capability, setRequestHandler's capability assertion
would throw, breaking app initialization at module load.

Auto-register { tools: { listChanged: true } } on first registerTool
call (pre-connect only), mirroring McpServer.registerTool behavior.

Fixes pdf-annotations e2e failures where the PDF canvas never rendered
because registerTool threw at module scope.

* pdf-server: replace app-tools with 1:1 interact command mapping

Converts the 5 placeholder app-registered tools into 12 tools that map
directly to the server's interact commands (navigate, search, find,
search_navigate, zoom, add_annotations, update_annotations,
remove_annotations, highlight_text, fill_form, get_text, get_screenshot)
plus the existing get-document-info.

Implementation stays DRY by dispatching through the existing
processCommands() handler — each tool callback constructs a PdfCommand
and runs it via a small runCommand() wrapper. For get_text and
get_screenshot, the page-data collection is extracted from
handleGetPages into a shared collectPageData() helper so results can
be returned directly instead of round-tripping through the server.

Tool names and zod schemas mirror the interact command parameter shapes
from server.ts so the model sees the same surface whether it goes
through interact or app-tools. The server-side interact tool is
unchanged and remains available for hosts without app-tool support.

* chore: drop unused test vars and stale Request/Result imports

* docs(spec): address review feedback on app tool registration

- Add outputSchema to Tool struct (matches SDK + core MCP)
- Reword "black box" bullets: drop stale screenshots reference, clarify no DOM access
- Clarify push vs pull contrast with explicit setWidgetState + ui/update-model-context refs
- Add Task-reference future-work bullet for tools outliving render lifecycle

* docs(spec): clarify app DOM is not host-introspectable; frame tools as pull complementing update-model-context push

* fix(app): emit title and omit absent outputSchema in tools/list

* feat(app): accept Standard Schema in registerTool/registerAppTool

App.registerTool and registerAppTool now accept any schema implementing
the Standard Schema spec (Zod ≥3.25, ArkType, Valibot, …) instead of
zod-only. Uses ~standard.validate / ~standard.jsonSchema directly, so
app.ts no longer imports zod at runtime — zod is now an optional peer.

Mirrors the StandardSchemaWithJSON type from
modelcontextprotocol/typescript-sdk#1689 so bumping to SDK v2 is a
drop-in import swap. Adds @standard-schema/spec (types-only) and a
hand-rolled non-zod test.

* docs(spec): reference core MCP Tasks for long-running app tools

App tools/call MAY be task-augmented per the core MCP Tasks utility
(spec 2025-11-25). Adds a Long-Running App Tools subsection: hosts proxy
tasks/* while the app is mounted; apps SHOULD delegate long-lived work
to the server so the task survives iframe teardown. Removes the stale
'future extension' bullet — Tasks is shipped.

* docs(spec): note Schema Validation accepts any Standard Schema library

* chore: clean unused-var and no-op-await diagnostics in app.ts and tests

* refactor(app): fold error prefix into validateStandardSchema; clarify registerAppTool runtime caveat

* chore(typedoc): mark RequestHandlerExtra as intentionally not exported

AppToolCallback (introduced with the Standard Schema migration) references
the local RequestHandlerExtra alias in its parameter type. The alias is a
private Parameters<> derivation and isn't part of the public API surface,
so add it to intentionallyNotExported alongside AppOptions/MethodSchema.

* fix(app): restore zod v3.25 compat via lazy z.toJSONSchema fallback

zod v3.25.x implements ~standard.validate but not ~standard.jsonSchema,
so constraining to StandardSchemaWithJSON broke the ^3.25.0 peer range.
Widen registerTool to StandardSchemaV1 and fall back to a lazy zod/v4
import for serialization when ~standard.jsonSchema is absent and
vendor==='zod'. Non-zod schemas without jsonSchema get a clear error.

* docs(spec): slim Long-Running App Tools to a pointer into core MCP Tasks

* chore: add TODO(sdk-v2) marker in standard-schema.ts

* fix(app): align registerTool runtime with declared types

- Handler reads registeredTool.{input,output}Schema so update() takes effect
- Call cb(extra) when no inputSchema, matching AppToolCallback<undefined>
- Throw on duplicate name; guard list_changed pre-connect; notify on register
- Drop misleading zod optional peer (still required by generated/schema.ts)
- examples: fix pdf search/find stale match count; threejs set-scene-source re-render
- spec: Zod → Standard Schema; clarify tools availability via tools/list after init

* feat(app): type structuredContent from outputSchema in registerTool

AppToolCallback gains an Out param: when outputSchema is provided,
structuredContent is required and typed via StandardSchemaV1.InferOutput,
with an `isError: true` escape hatch. Without outputSchema, return type
is unchanged (CallToolResult). Uses intersection rather than Omit since
CallToolResult's index signature swallows Omit's known keys.

Also drops the `as any` casts on z.object(...) in tests — zod 4 satisfies
StandardSchemaV1 directly.

* fix(app): registerTool edge cases + example tool correctness

App.registerTool:
- Skip outputSchema validation when result.isError (matches AppToolResult type)
- Pin callback arity to original config.inputSchema; only the validation schema is mutable via update()
- Default missing tools/call arguments to {}
- remove() is a no-op if the handle is stale (re-registered or already removed)
- Gate list_changed notifications on the listChanged capability

Examples:
- threejs: propagate executeThreeCode failures to onSceneError/onSceneRendering; catch updateModelContext rejection
- wiki-explorer: search-article preserves graph on no-match
- budget-allocator: fix category/stage values in tool descriptions

* feat(app,app-bridge): guard requests sent before handshake completes (#620)

* feat(app,app-bridge): guard requests sent before handshake completes

Calling host-bound methods before the ui/initialize →
ui/notifications/initialized handshake completes can race the handshake
on strict hosts and leave the iframe permanently hidden.

App (View side):
- All 8 host-bound methods (callServerTool, readServerResource,
  listServerResources, sendMessage, updateModelContext, openLink,
  downloadFile, requestDisplayMode) now check that connect() has sent
  the initialized notification.
- New AppOptions.strict (default false): console.error when false,
  throw when true. AppOptions is now exported.
- useApp() forwards strict to the App constructor.
- Flag resets on reconnect.

AppBridge (Host side):
- replaceRequestHandler is overridden to wrap every host-bound handler
  with a console.warn if the request arrives before
  ui/notifications/initialized. Never throws. ui/initialize and ping
  use setRequestHandler directly and are exempt; notifications are
  unaffected.
- Catches Views that hand-roll postMessage without the SDK.
- Flag resets on reconnect.

Refs anthropics/claude-ai-mcp#61, anthropics/claude-ai-mcp#149.

* fix(docs): drop AppOptions from intentionallyNotExported now that it is exported

---------

Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
Olivier Chafik 2026-04-21 13:46:13 +01:00 • committed by GitHub
commit 3fb521b71f
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 3864 additions and 120 deletions
Download patch file Download diff file Expand all files Collapse all files

748
specification/draft/apps.mdx
View file

@ -506,11 +506,23 @@ If the Host is a web page, it MUST wrap the View and communicate with it through
### Standard MCP Messages
UI iframes can use the following subset of standard MCP protocol messages:
UI iframes can use the following subset of standard MCP protocol messages.
Note that `tools/call` and `tools/list` flow **bidirectionally**:
- **App → Host → Server**: Apps call server tools (requires host `serverTools` capability)
- **Host → App**: Host calls app-registered tools (requires app `tools` capability)
**Tools:**
- `tools/call` - Execute a tool on the MCP server
- `tools/call` - Execute a tool (bidirectional)
- **App → Host**: Call server tool via host proxy
- **Host → App**: Call app-registered tool
- `tools/list` - List available tools (bidirectional)
- **App → Host**: List server tools
- **Host → App**: List app-registered tools
- `notifications/tools/list_changed` - Notify when tool list changes (bidirectional)
- **Server → Host → App**: Server tools changed
- **App → Host**: App-registered tools changed
**Resources:**
@ -1200,6 +1212,95 @@ Host behavior:
- If multiple updates are received before the next user message, Host SHOULD only send the last update to the model
- MAY display context updates to the user
#### Requests (Host → App)
When Apps declare the `tools` capability, the Host can send standard MCP tool requests to the App:
`tools/call` - Execute an App-registered tool
```typescript
// Request (Host → App)
{
jsonrpc: "2.0",
id: 1,
method: "tools/call",
params: {
name: string, // Name of app-registered tool to execute
arguments?: object // Tool arguments (validated against inputSchema)
}
}
// Success Response (App → Host)
{
jsonrpc: "2.0",
id: 1,
result: {
content: Array<ContentBlock>, // Result for model context
structuredContent?: object, // Optional structured data for UI
isError?: boolean, // True if tool execution failed
_meta?: object // Optional metadata
}
}
// Error Response
{
jsonrpc: "2.0",
id: 1,
error: {
code: number,
message: string
}
}
```
**App Behavior:**
- Apps MUST implement `oncalltool` handler if they declare `tools` capability
- Apps SHOULD validate tool names and arguments
- Apps MAY use `app.registerTool()` SDK helper for automatic validation
- Apps SHOULD return `isError: true` for tool execution failures
`tools/list` - List App-registered tools
```typescript
// Request (Host → App)
{
jsonrpc: "2.0",
id: 2,
method: "tools/list",
params: {
cursor?: string // Optional pagination cursor
}
}
// Response (App → Host)
{
jsonrpc: "2.0",
id: 2,
result: {
tools: Array<Tool>, // List of available tools
nextCursor?: string // Pagination cursor if more tools exist
}
}
```
**Tool Structure** (identical to [core MCP `Tool`](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#tool)):
```typescript
interface Tool {
name: string; // Unique tool identifier
title?: string; // Display name
description?: string; // Human-readable description
inputSchema: object; // JSON Schema for arguments
outputSchema?: object; // JSON Schema for structuredContent
annotations?: ToolAnnotations; // MCP tool annotations (e.g., readOnlyHint)
_meta?: object;
}
```
**App Behavior:**
- Apps MUST implement `onlisttools` handler if they declare `tools` capability
- Apps SHOULD return complete tool metadata including schemas
- Apps MAY filter tools based on context or permissions
#### Notifications (Host → View)
`ui/notifications/tool-input` - Host MUST send this notification with the complete tool arguments after the View's initialize request completes.
@ -1611,6 +1712,446 @@ This pattern enables interactive, self-updating views.
Note: Tools with `visibility: ["app"]` are hidden from the agent but remain callable by apps via `tools/call`. This enables UI-only interactions (refresh buttons, form submissions) without exposing implementation details to the model. See the Visibility section under Resource Discovery for details.
### App-Provided Tools
Apps can register their own tools that hosts and agents can call, making apps **introspectable and accessible** to the model. This complements the existing capability where apps call server tools (via host proxy).
#### Motivation: Semantic Introspection
Without tool registration, apps are opaque to the model:
- The host renders the app in a sandboxed iframe and has no guaranteed access to its internals — apps may embed further cross-origin iframes (via `frameDomains`), and even where same-origin, DOM access is not part of the host↔app contract
- The model therefore cannot query app state or discover what operations the app supports
With tool registration, apps expose a semantic interface:
- The model discovers available operations via `tools/list`
- The model queries app state via tools (e.g., `get_board_state`)
- The model executes actions via tools (e.g., `make_move`)
- Apps return structured data rather than relying on the host to interpret rendered output
This is *pull*-based and complements the *push*-based [`ui/update-model-context`](#uiupdate-model-context) request already defined in this spec (and analogous mechanisms elsewhere, e.g. OAI Apps SDK's [`setWidgetState()`](https://developers.openai.com/apps-sdk/reference/sdk#setwidgetstate)). Push lets an app proactively keep the model's context current; pull lets the agent query and command the app on demand. Apps may use either or both.
#### App Tool Registration
Apps register tools using the SDK's `registerTool()` method:
```typescript
import { App } from '@modelcontextprotocol/ext-apps';
import { z } from 'zod';
const app = new App(
{ name: "TicTacToe", version: "1.0.0" },
{ tools: { listChanged: true } } // Declare tool capability
);
// Register a tool with schema validation
const moveTool = app.registerTool(
"tictactoe_move",
{
description: "Make a move in the tic-tac-toe game",
inputSchema: z.object({
position: z.number().int().min(0).max(8),
player: z.enum(['X', 'O'])
}),
outputSchema: z.object({
board: z.array(z.string()).length(9),
winner: z.enum(['X', 'O', 'draw', null]).nullable()
}),
annotations: {
readOnlyHint: false // This tool has side effects
}
},
async (params) => {
// Validate and execute move
const newBoard = makeMove(params.position, params.player);
const winner = checkWinner(newBoard);
return {
content: [{
type: "text",
text: `Move made at position ${params.position}`
}],
structuredContent: {
board: newBoard,
winner
}
};
}
);
await app.connect(new PostMessageTransport(window.parent));
```
**Registration Options:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Unique tool identifier |
| `description` | string | No | Human-readable description for agent |
| `inputSchema` | [Standard Schema](https://standardschema.dev/) | No | Validates arguments; serialized to JSON Schema for `tools/list` |
| `outputSchema` | [Standard Schema](https://standardschema.dev/) | No | Validates `structuredContent` |
| `annotations` | ToolAnnotations | No | MCP tool hints (e.g., `readOnlyHint`) |
| `_meta` | object | No | Custom metadata |
Apps can also implement tool handling manually without the SDK:
```javascript
app.oncalltool = async (params, extra) => {
if (params.name === "tictactoe_move") {
// Manual validation
if (typeof params.arguments?.position !== 'number') {
throw new Error("Invalid position");
}
// Execute tool
const newBoard = makeMove(params.arguments.position, params.arguments.player);
return {
content: [{ type: "text", text: "Move made" }],
structuredContent: { board: newBoard }
};
}
throw new Error(`Unknown tool: ${params.name}`);
};
app.onlisttools = async () => {
return {
tools: [
{
name: "tictactoe_move",
description: "Make a move in the game",
inputSchema: {
type: "object",
properties: {
position: { type: "number", minimum: 0, maximum: 8 },
player: { type: "string", enum: ["X", "O"] }
},
required: ["position", "player"]
}
}
]
};
};
```
#### Tool Lifecycle
Registered tools support dynamic lifecycle management:
**Enable/Disable:**
```typescript
const tool = app.registerTool("my_tool", config, callback);
// Disable tool (hide from tools/list)
tool.disable();
// Re-enable tool
tool.enable();
```
When a tool is disabled/enabled, the app automatically sends `notifications/tools/list_changed` (if the app declared `listChanged: true` capability).
**Update:**
```typescript
// Update tool description or schema
tool.update({
description: "New description",
inputSchema: newSchema
});
```
Updates also trigger `notifications/tools/list_changed`.
**Remove:**
```typescript
// Permanently remove tool
tool.remove();
```
#### Long-Running App Tools
App tools are bounded by the app's render lifecycle. For work that may outlive a single render, app `tools/call` MAY be task-augmented per [core MCP Tasks](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/tasks); hosts proxy the `tasks/*` methods to the app exactly as they proxy `tools/call`. Because the iframe can be torn down at any time, apps SHOULD delegate long-lived work to the server (via `callServerTool()`) and return the server's task handle, so the host can continue polling the server after teardown.
#### Schema Validation
The SDK validates input and output against any [Standard Schema](https://standardschema.dev/)–compatible library (Zod, ArkType, Valibot, …). Examples below use Zod:
**Input Validation:**
```typescript
app.registerTool(
"search",
{
inputSchema: z.object({
query: z.string().min(1).max(100),
limit: z.number().int().positive().default(10)
})
},
async (params) => {
// params.query is guaranteed to be a string (1-100 chars)
// params.limit is guaranteed to be a positive integer (default 10)
return performSearch(params.query, params.limit);
}
);
```
If the host sends invalid arguments, the tool automatically returns an error before the callback is invoked.
**Output Validation:**
```typescript
app.registerTool(
"get_status",
{
outputSchema: z.object({
status: z.enum(['ready', 'busy', 'error']),
timestamp: z.string().datetime()
})
},
async () => {
return {
content: [{ type: "text", text: "Status retrieved" }],
structuredContent: {
status: 'ready',
timestamp: new Date().toISOString()
}
};
}
);
```
If the callback returns data that doesn't match `outputSchema`, the tool returns an error.
#### Complete Example: Introspectable Tic-Tac-Toe
This example demonstrates how apps expose semantic interfaces through tools:
```typescript
import { App } from '@modelcontextprotocol/ext-apps';
import { z } from 'zod';
// Game state
let board: Array<'X' | 'O' | null> = Array(9).fill(null);
let currentPlayer: 'X' | 'O' = 'X';
let moveHistory: number[] = [];
const app = new App(
{ name: "TicTacToe", version: "1.0.0" },
{ tools: { listChanged: true } }
);
// Agent can query semantic state directly
app.registerTool(
"get_board_state",
{
description: "Get current game state including board, current player, and winner",
outputSchema: z.object({
board: z.array(z.enum(['X', 'O', null])).length(9),
currentPlayer: z.enum(['X', 'O']),
winner: z.enum(['X', 'O', 'draw', null]).nullable(),
moveHistory: z.array(z.number())
})
},
async () => {
return {
content: [{
type: "text",
text: `Board: ${board.map(c => c || '-').join('')}, Player: ${currentPlayer}`
}],
structuredContent: {
board,
currentPlayer,
winner: checkWinner(board),
moveHistory
}
};
}
);
// Agent can execute moves
app.registerTool(
"make_move",
{
description: "Place a piece at the specified position",
inputSchema: z.object({
position: z.number().int().min(0).max(8)
}),
annotations: { readOnlyHint: false }
},
async ({ position }) => {
if (board[position] !== null) {
return {
content: [{ type: "text", text: "Position already taken" }],
isError: true
};
}
board[position] = currentPlayer;
moveHistory.push(position);
const winner = checkWinner(board);
currentPlayer = currentPlayer === 'X' ? 'O' : 'X';
return {
content: [{
type: "text",
text: `Player ${board[position]} moved to position ${position}` +
(winner ? `. ${winner} wins!` : '')
}],
structuredContent: {
board,
currentPlayer,
winner,
moveHistory
}
};
}
);
// Agent can reset game
app.registerTool(
"reset_game",
{
description: "Reset the game board to initial state",
annotations: { readOnlyHint: false }
},
async () => {
board = Array(9).fill(null);
currentPlayer = 'X';
moveHistory = [];
return {
content: [{ type: "text", text: "Game reset" }],
structuredContent: { board, currentPlayer, moveHistory }
};
}
);
await app.connect(new PostMessageTransport(window.parent));
function checkWinner(board: Array<'X' | 'O' | null>): 'X' | 'O' | 'draw' | null {
const lines = [
[0, 1, 2], [3, 4, 5], [6, 7, 8], // rows
[0, 3, 6], [1, 4, 7], [2, 5, 8], // columns
[0, 4, 8], [2, 4, 6] // diagonals
];
for (const [a, b, c] of lines) {
if (board[a] && board[a] === board[b] && board[a] === board[c]) {
return board[a];
}
}
return board.every(cell => cell !== null) ? 'draw' : null;
}
```
**Agent Interaction:**
```typescript
// 1. Discover available operations
const { tools } = await bridge.sendListTools({});
// → ["get_board_state", "make_move", "reset_game"]
// 2. Query semantic state (not visual/DOM)
const state = await bridge.sendCallTool({
name: "get_board_state",
arguments: {}
});
// → { board: [null, null, null, ...], currentPlayer: 'X', winner: null }
// 3. Execute actions based on semantic understanding
if (state.structuredContent.board[4] === null) {
await bridge.sendCallTool({
name: "make_move",
arguments: { position: 4 }
});
}
// 4. Query updated state
const newState = await bridge.sendCallTool({
name: "get_board_state",
arguments: {}
});
// → { board: [null, null, null, null, 'X', null, ...], currentPlayer: 'O', ... }
```
The agent interacts with the app through semantic operations rather than visual interpretation.
#### Tool Flow Directions
**Existing Flow (unchanged): App → Host → Server**
Apps call server tools (proxied by host):
```typescript
// App calls server tool
const result = await app.callServerTool("get_weather", { location: "NYC" });
```
Requires host `serverTools` capability.
**New Flow: Host/Agent → App**
Host/Agent calls app-registered tools:
```typescript
// Host calls app tool
const result = await bridge.sendCallTool({
name: "tictactoe_move",
arguments: { position: 4 }
});
```
Requires app `tools` capability.
**Key Distinction:**
| Aspect | Server Tools | App Tools |
|--------|-------------|-----------|
| **Lifetime** | Persistent (server process) | Ephemeral (while app loaded) |
| **Source** | MCP Server | App JavaScript |
| **Trust** | Trusted | Sandboxed (untrusted) |
| **Discovery** | Server `tools/list` | App `tools/list` (when app declares capability) |
| **When Available** | Always | Only while app is loaded |
#### Use Cases
**Introspection:** Agent queries app state semantically — the app's DOM is not exposed to the host or model
**Voice mode:** Agent drives app interactions programmatically based on voice commands
**Accessibility:** Structured state and operations more accessible than visual rendering
**Complex workflows:** Agent discovers available operations and coordinates multi-step interactions
**Stateful apps:** Apps expose operations (move, reset, query) rather than pushing state updates via messages
#### Security Implications
App tools run in **sandboxed iframes** (untrusted). See Security Implications section for detailed mitigations.
Key considerations:
- App tools could provide misleading descriptions
- Tool namespacing needed to avoid conflicts with server tools
- Resource limits (max tools, execution timeouts)
- Audit trail for app tool invocations
- User confirmation for tools with side effects
#### Relation to WebMCP
This feature is inspired by [WebMCP](https://github.com/webmachinelearning/webmcp) (W3C incubation), which proposes allowing web pages to register JavaScript functions as tools via `navigator.modelContext.registerTool()`.
Key differences:
- **WebMCP**: General web pages, browser API, manifest-based discovery
- **This spec**: MCP Apps, standard MCP messages, capability-based negotiation
Similar to WebMCP but without turning the App (embedded page) into an MCP server - apps register tools within the App/Host architecture.
See [ext-apps#35](https://github.com/modelcontextprotocol/ext-apps/issues/35) for discussion.
### Client\<\>Server Capability Negotiation
Clients and servers negotiate MCP Apps support through the standard MCP extensions capability mechanism (defined in SEP-1724).
@ -1681,15 +2222,104 @@ if (uiCap?.mimeTypes?.includes(RESOURCE_MIME_TYPE)) {
- Tools MUST return meaningful content array even when UI is available
- Servers MAY register different tool variants based on host capabilities
#### App (Guest UI) Capabilities
Apps advertise their capabilities in the `ui/initialize` request to the host. When an app supports tool registration, it includes the `tools` capability:
```json
{
"method": "ui/initialize",
"params": {
"appInfo": {
"name": "TicTacToe",
"version": "1.0.0"
},
"appCapabilities": {
"tools": {
"listChanged": true
}
}
}
}
```
The host responds with its own capabilities, including support for proxying server tools:
```json
{
"result": {
"hostInfo": {
"name": "claude-desktop",
"version": "1.0.0"
},
"hostCapabilities": {
"serverTools": {
"listChanged": true
},
"openLinks": {},
"logging": {}
}
}
}
```
**App Capability: `tools`**
When present, the app can register tools that the host and agent can call.
- `listChanged` (boolean, optional): If `true`, the app will send `notifications/tools/list_changed` when tools are added, removed, or modified
**Host Capability: `serverTools`**
When present, the host can proxy calls from the app to MCP server tools.
- `listChanged` (boolean, optional): If `true`, the host will send `notifications/tools/list_changed` when server tools change
These capabilities are independent - an app can have one, both, or neither.
**TypeScript Types:**
```typescript
interface McpUiAppCapabilities {
tools?: {
listChanged?: boolean;
};
}
interface McpUiHostCapabilities {
serverTools?: {
listChanged?: boolean;
};
openLinks?: {};
logging?: {};
}
```
### Extensibility
This specification defines the Minimum Viable Product (MVP) for MCP Apps. Future extensions may include:
This specification defines the Minimum Viable Product (MVP) for MCP Apps.
**Included in MVP:**
- **App-Provided Tools:** Apps can register tools via `app.registerTool()` that agents can call
- Bidirectional tool flow (Apps consume server tools AND provide app tools)
- Full lifecycle management (enable/disable/update/remove)
- Schema validation via [Standard Schema](https://standardschema.dev/) (Zod, ArkType, Valibot, …)
- Tool list change notifications
**Content Types (deferred from MVP):**
- `externalUrl`: Embed external web applications (e.g., `text/uri-list`)
**Advanced Features (see Future Considerations):**
**Advanced Tool Features (future extensions):**
- Tool namespacing standards and conventions
- Standardized permission model specifications
- Tool categories/tags for organization
- Cross-app tool composition
- Tool marketplace/discovery mechanisms
**Other Advanced Features (see Future Considerations):**
- Support multiple UI resources in a tool response
- State persistence and restoration
@ -1727,7 +2357,7 @@ This proposal synthesizes feedback from the UI CWG and MCP-UI community, host im
- Reuses existing MCP infrastructure (type definitions, error handling, timeouts)
- UI developers can use standard MCP SDK (`@modelcontextprotocol/sdk`) or alternatives
- Automatic compatibility with future MCP features (long-running tools, sampling, etc.)
- Automatic compatibility with core MCP features (Tasks for long-running calls, sampling, etc.)
- Better auditability through structured JSON-RPC messages
- Reduces maintenance burden (no parallel protocol to evolve)
@ -1789,6 +2419,37 @@ This proposal synthesizes feedback from the UI CWG and MCP-UI community, host im
- **Boolean `private` flag:** Simpler but less flexible; doesn't express model-only tools.
- **Flat `ui/visibility` key:** Rejected in favor of nested structure for consistency with future `_meta.ui` fields.
#### 6. App Tool Registration Support
**Decision:** Enable Apps to register tools using standard MCP `tools/call` and `tools/list` messages, making tools flow bidirectionally between Apps and Hosts.
**Rationale:**
- **Semantic introspection:** Apps expose state and operations in a structured, machine-readable form. Hosts have no guaranteed DOM access into an app (which may itself nest cross-origin frames via `frameDomains`), so a tool surface is the only reliable introspection path
- **Protocol reuse:** Reuses existing MCP tool infrastructure (`tools/call`, `tools/list`, `notifications/tools/list_changed`) instead of inventing new message types
- **WebMCP alignment:** Brings WebMCP's vision of "JavaScript functions as tools" to MCP Apps while staying MCP-native
- **Agent-driven interaction:** Agents can pull app state and issue commands on demand, complementing push-style [`ui/update-model-context`](#uiupdate-model-context)
- **Bidirectional symmetry:** Apps act as both MCP clients (calling server tools) and MCP servers (providing app tools), creating clean architectural symmetry
- **Use case coverage:** Enables interactive games, stateful forms, complex workflows, and reusable widgets
**Alternatives considered:**
- **Custom app-action API:** Rejected because it would duplicate MCP's existing tool infrastructure and create parallel protocol semantics. Using standard `tools/call` means automatic compatibility with future MCP features and better ecosystem integration.
- **Server-side proxy tools:** Apps could expose operations by having the server register proxy tools that communicate back to the app. Rejected because it doesn't leverage the app's JavaScript execution environment, adds unnecessary round-trips, and couples app functionality to server implementation.
- **Resources instead of tools:** Apps could expose state via `resources/read` rather than tools. Rejected because resources have wrong semantics (passive data retrieval vs. active operations), don't support parameters well, and don't convey operational intent.
**Security implications:**
Apps are forward-deployed emanations of server tools, running in the client context. Hosts should consider how to handle tool call approval:
- Per-app-instance approval (confirm each time a specific app instance calls a tool)
- Per-server approval (approve all apps from a trusted server)
- Per-tool approval (approve based on tool semantics and annotations)
- Clear attribution showing which app instance is calling a tool
- Audit trails for app tool calls
See [Security Implications: App-Provided Tools Security](#5-app-provided-tools-security) for detailed considerations.
### Backward Compatibility
The proposal builds on the existing core protocol. There are no incompatibilities.
@ -1881,6 +2542,83 @@ const allowAttribute = allowList.join(' ');
- Host SHOULD warn users when UI requires external domain access
- Host MAY implement global domain allowlists/blocklists
#### 5. App-Provided Tools Security
Apps can register their own tools that agents can call. Apps are forward-deployed emanations of server tools, running in the client context. Hosts need to decide how to handle approval for app tool calls.
**Approval Considerations:**
App-provided tools introduce additional approval considerations:
- **Tool description accuracy:** Apps may describe tools in ways that don't fully capture side effects
- **Namespace conflicts:** Apps could register tools with names conflicting with server tools
- **Resource consumption:** Apps could register many tools or implement slow callbacks
- **Data validation:** Tool results should match declared schemas
- **Semantic clarity:** Tool operations should be clear from their descriptions
**Approval Granularity:**
Hosts have discretion in how they handle app tool call approval:
1. **Per-app-instance approval:** Confirm each time a specific app instance's tool is called
2. **Per-server approval:** Trust all apps from servers the user has approved
3. **Per-tool approval:** Approve based on tool annotations (e.g., `readOnlyHint`)
4. **Hybrid approaches:** Combine strategies (e.g., auto-approve read-only tools from trusted servers)
**Host Protections:**
Hosts SHOULD implement the following protections for app-provided tools:
1. **Clear Attribution:**
- Display tool source in agent's tool list (e.g., "Tool from TicTacToe App")
- Visually distinguish app tools from server tools in UI
- Show app name and version in tool call confirmations
2. **User Confirmation:**
- Require explicit user approval for tools with `readOnlyHint: false`
- Consider auto-approving tools with `readOnlyHint: true` after review
- Implement per-app permission settings (always allow, always deny, ask)
3. **Namespace Management:**
- Recommend or enforce tool name prefixes (e.g., `app:move`, `tictactoe:move`)
- Prevent apps from registering tool names that conflict with server tools
- Document namespace conventions for app developers
4. **Resource Limits:**
- Limit maximum number of tools per app (recommended: 50)
- Enforce execution timeouts for tool callbacks (recommended: 30 seconds)
- Limit tool result sizes (recommended: 10 MB)
- Throttle `tools/list_changed` notifications to prevent spam
5. **Audit Trail:**
- Log all app tool registrations with timestamps
- Log all app tool calls with arguments and results
- Provide audit interface for users to review app tool activity
6. **Result Validation:**
- Validate tool results match declared schemas
- Sanitize result content before displaying to user or agent
- Reject results that appear malicious (e.g., phishing content)
**Permission Model:**
Hosts MAY implement different permission levels based on tool annotations:
| Annotation | Recommended Permission | Example |
|---------------------|------------------------|-------------------|
| `readOnlyHint: true`| Auto-approve (with caution) | `get_board_state()` |
| `readOnlyHint: false` | User confirmation required | `make_move()` |
| No annotation | User confirmation required (safe default) | Any tool |
**App Tool Lifecycle:**
App tools MUST be tied to the app's lifecycle:
- Tools become available once the app advertises the `tools` capability in `ui/initialize` and the host issues `tools/list`; subsequent changes are signaled via `notifications/tools/list_changed`
- Tools automatically disappear when app iframe is torn down
- Hosts MUST NOT persist app tool registrations across sessions
- Calling a tool from a closed app MUST return an error
### Other risks
- **Social engineering:** UI can still display misleading content. Hosts should clearly indicate sandboxed UI boundaries.