MCP App Tools — Letting the Host Call Tools Inside Your View

MCP Apps SDK

Overview

MCP Apps is bidirectional. In addition to the View calling tools on the originating MCP server (see callServerTool), the View itself can act like a tiny MCP server — registering tools that the host or model can call. App-side tools are useful when the answer lives inside the View and can’t be answered by the server:

DOM and selection state — get the user’s current selection, scroll position, or visible viewport
Form state — submit values from a multi-step wizard or pending edits
Local computation — derive values from data the View has already loaded
User intent — surface explicit UI actions (a “Save” button, a confirm dialog) to the model

This page ties together the four pieces that make app-side tools work: the tools capability, onlisttools, oncalltool, and list-changed notifications for dynamic tool lists.

Two ways to register tools

The SDK offers two equivalent patterns. Pick the one that matches the shape of your app.

Static list — `onlisttools` + `oncalltool`

Declare a fixed list once. The host queries onlisttools, then dispatches calls to oncalltool. Good for apps where the tool set never changes.

Dynamic registry — `app.registerTool()`

Add, update, enable, disable, or remove tools at runtime. Each call returns a handle with enable(), disable(), remove(), and update(). The SDK builds the tool list, dispatches calls, and sends list-changed notifications automatically when the capability is enabled.

In the sunpeak framework, use useAppTools() for the static pattern or useRegisterTool() for the dynamic pattern.

1. Declare the `tools` capability

The host only routes tools/list and tools/call to the View if the View declared support during initialization. Pass tools in the capabilities argument to the App constructor.

const app = new App(
  { name: "MyApp", version: "1.0.0" },
  { tools: { listChanged: true } }, // declares app-side tool support
);

Set listChanged: true only if you plan to add or remove tools at runtime. The host will re-query onlisttools whenever you send a notifications/tools/list_changed notification. When you call app.registerTool() before connect(), the SDK declares { tools: { listChanged: true } } automatically if you did not provide a tools capability. Manual onlisttools and oncalltool handlers still require you to declare the capability yourself.

2. Declare which tools the app exposes

Static — `onlisttools`

Return an array of MCP Tool definitions. Each must have a name and an inputSchema (with type: "object").

app.onlisttools = async () => ({
  tools: [
    {
      name: "get-selection",
      description: "Return the user's current text selection",
      inputSchema: { type: "object" },
    },
    {
      name: "insert-text",
      description: "Insert text at the current cursor position",
      inputSchema: {
        type: "object",
        properties: { text: { type: "string" } },
        required: ["text"],
      },
    },
  ],
});

Dynamic — `app.registerTool()`

Define tools in code with Standard Schema (Zod, ArkType, Valibot) for input validation. The SDK populates onlisttools and dispatches oncalltool automatically.

import { z } from "zod";

const insertHandle = app.registerTool(
  "insert-text",
  {
    description: "Insert text at the current cursor position",
    inputSchema: z.object({ text: z.string() }),
  },
  ({ text }) => {
    insertAtCursor(text);
    return { content: [{ type: "text", text: "Inserted" }] };
  },
);

The returned handle exposes lifecycle methods:

Method	Effect
`update(config)`	Update the title, description, schemas, annotations, metadata, or enabled state
`enable()`	Re-list the tool after `disable()`
`disable()`	Hide the tool from the host (still registered)
`remove()`	Permanently remove the tool

Register handlers and tools before calling connect() — handlers registered after the initialization handshake will miss the first tools/list call from the host.

3. Handle tool calls

When the host calls one of the View’s tools, it arrives in oncalltool. Return a CallToolResult with content (for the model) and optional structuredContent (for any UI that reads it).

app.oncalltool = async (params) => {
  switch (params.name) {
    case "get-selection":
      return {
        content: [{ type: "text", text: window.getSelection()?.toString() ?? "" }],
      };

    case "insert-text": {
      const { text } = params.arguments as { text: string };
      insertAtCursor(text);
      return {
        content: [{ type: "text", text: "Inserted" }],
      };
    }

    default:
      throw new Error(`Unknown tool: ${params.name}`);
  }
};

If you use registerTool, you skip this — each tool’s callback runs automatically. The dispatcher checks the registry first, falling back to oncalltool for any unmatched name.

Returning errors

Throw to fail the request at the transport level. Return { isError: true, content: [...] } to surface a tool-level error that the model can see and recover from. Prefer the latter for anything the model could act on.

app.oncalltool = async (params) => {
  if (params.name === "submit-form" && !formIsValid()) {
    return {
      isError: true,
      content: [{ type: "text", text: "Form has validation errors" }],
    };
  }
  // ...
};

Dynamic tool lists

The dynamic registry sends notifications/tools/list_changed automatically after registerTool(), update(), enable(), disable(), or remove() when the View has initialized with listChanged: true.

const saveHandle = app.registerTool("save", { description: "Save changes" }, saveHandler);

saveHandle.disable(); // SDK notifies the host
saveHandle.enable(); // SDK notifies the host again

Use sendToolListChanged() when you manage a custom onlisttools result outside the registry:

let exposeSelectionTool = false;

editor.on("dirty", async () => {
  exposeSelectionTool = true;
  await app.sendToolListChanged();
});

List-changed notifications work only when the View declared tools: { listChanged: true } and the Host supports app-side tools. The Host then re-runs tools/list and updates the model’s available tools for the next turn.

Tool visibility — model, app, or both

The _meta.ui.visibility array on a tool controls who can call it: "model", "app", or both. App-side tools that are surfaced to the model should remain ["model", "app"] (the default). Set ["app"] for tools that are pure UI plumbing (refresh buttons, pagination) and shouldn’t clutter the model’s tool list. See Tool _meta for the full discussion.

app.registerTool(
  "refresh",
  {
    description: "Reload data — UI only",
    _meta: { ui: { visibility: ["app"] } },
  },
  refreshHandler,
);

End-to-end example

import { App } from "@modelcontextprotocol/ext-apps";
import { z } from "zod";

const app = new App(
  { name: "DocEditor", version: "1.0.0" },
  { tools: { listChanged: true } },
);

// Static handler for tools known up front
app.oncalltool = async (params) => {
  if (params.name === "get-selection") {
    return {
      content: [{ type: "text", text: window.getSelection()?.toString() ?? "" }],
    };
  }
  throw new Error(`Unknown tool: ${params.name}`);
};

app.onlisttools = async () => ({
  tools: [
    {
      name: "get-selection",
      description: "Read the user's current selection",
      inputSchema: { type: "object" },
    },
  ],
});

// Dynamic tool added later from UI state
const insertHandle = app.registerTool(
  "insert-text",
  {
    description: "Insert text at the cursor",
    inputSchema: z.object({ text: z.string() }),
  },
  ({ text }) => {
    insertAtCursor(text);
    return { content: [{ type: "text", text: "Inserted" }] };
  },
);

await app.connect();

onlisttools — request handler for tools/list
oncalltool — request handler for tools/call
registerTool — dynamic registry on the App
sendToolListChanged — notify the host of changes
Tool _meta — visibility and resource linkage
useAppTools and useRegisterTool — sunpeak React wrappers

Overview

App

MCP

React

Server

Styling

Types

MCP App Tools — Letting the Host Call Tools Inside Your View

Overview

Two ways to register tools

Static list — `onlisttools` + `oncalltool`

Dynamic registry — `app.registerTool()`

1. Declare the `tools` capability

2. Declare which tools the app exposes

Static — `onlisttools`

Dynamic — `app.registerTool()`

3. Handle tool calls

Returning errors

Dynamic tool lists

Tool visibility — model, app, or both

End-to-end example

​Overview

​Two ways to register tools

​Static list — onlisttools + oncalltool

​Dynamic registry — app.registerTool()

​1. Declare the tools capability

​2. Declare which tools the app exposes

​Static — onlisttools

​Dynamic — app.registerTool()

​3. Handle tool calls

​Returning errors

​Dynamic tool lists

​Tool visibility — model, app, or both

​End-to-end example

​Related

Overview

Two ways to register tools

Static list — `onlisttools` + `oncalltool`

Dynamic registry — `app.registerTool()`

1. Declare the `tools` capability

2. Declare which tools the app exposes

Static — `onlisttools`

Dynamic — `app.registerTool()`

3. Handle tool calls

Returning errors

Dynamic tool lists

Tool visibility — model, app, or both

End-to-end example

Related