MCP Apps oncalltool - Handle Incoming Tool Calls

MCP Apps SDK

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

Overview

oncalltool is a request handler that receives tool calls from the host directed at your app. This enables bidirectional tool communication — in addition to calling server tools, the host (or model) can call tools that the View implements. To use oncalltool, you must declare the tools capability when constructing the App. The host discovers available tools through onlisttools, then calls them through this handler. Because this is a request handler, the host waits for your response. Return a result object containing content blocks, or throw an error to signal failure.

Signature

app.oncalltool = async (params: {
  name: string;
  arguments?: Record<string, unknown>;
}) => Promise<CallToolResult>;

Parameters

params

object

required

The tool call parameters sent by the host.

name

string

required

Name of the tool being called. Must match one of the tools declared in onlisttools.

arguments

Record<string, unknown>

Tool arguments as key-value pairs. The shape corresponds to the tool’s inputSchema.

Usage

Declare tools capability and handle calls

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

app.oncalltool = async (params) => {
  if (params.name === "get-selection") {
    return { content: [{ type: "text", text: selectedText }] };
  }
  throw new Error(`Unknown tool: ${params.name}`);
};

await app.connect();

Handle multiple tools with structured results

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

    case "get-form-data":
      return {
        content: [{ type: "text", text: JSON.stringify(collectFormData()) }],
      };

    case "set-highlight": {
      const { selector, color } = params.arguments as {
        selector: string;
        color: string;
      };
      highlightElement(selector, color);
      return {
        content: [{ type: "text", text: "Highlighted successfully" }],
      };
    }

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

Return errors without throwing

For expected failures, return an error result instead of throwing:

app.oncalltool = async (params) => {
  if (params.name === "get-file") {
    const file = files.get(params.arguments?.id as string);
    if (!file) {
      return {
        isError: true,
        content: [{ type: "text", text: `File not found: ${params.arguments?.id}` }],
      };
    }
    return { content: [{ type: "text", text: file.contents }] };
  }
  throw new Error(`Unknown tool: ${params.name}`);
};

App Tools guide — end-to-end pattern for registering tools and handling host calls
Event Handlers overview — all notification and request handlers
onlisttools — declare the tools your app provides
useAppTools — sunpeak React convenience hook for app-side tools
App Class constructor — declaring tools capability

​Overview

​Signature

​Parameters

​Usage

​Declare tools capability and handle calls

​Handle multiple tools with structured results

​Return errors without throwing

​Related

Overview

Signature

Parameters

Usage

Declare tools capability and handle calls

Handle multiple tools with structured results

Return errors without throwing

Related