Skip to main content
MCP Apps SDK 
import { App } from "@modelcontextprotocol/ext-apps";

​
Overview

callServerTool lets the View invoke any tool registered on the originating MCP server. The host proxies the request to the server and returns the result. This is the primary mechanism for UI-driven server interactions — for example, fetching data, submitting forms, or triggering server-side actions from a button click. Tool-level execution errors are returned inside the result object with isError: true rather than throwing exceptions. Only transport or protocol failures throw. Always check result.isError before consuming the response. For tools that should only be callable from the View (not the model), register them with visibility: ["app"] on the server side. See registerAppTool for details.

​
Signature

async callServerTool(
  params: { name: string; arguments?: Record<string, unknown> },
  options?: RequestOptions,
): Promise<CallToolResult>

​
Parameters

​
params
object
required
The tool call parameters.
​
name
string
required
The name of the server tool to call. Must match a tool registered on the MCP server.
​
arguments
Record<string, unknown>
Arguments to pass to the tool. The shape must match the tool’s inputSchema. Omit if the tool takes no arguments.
​
options
RequestOptions
Optional request configuration.
​
signal
AbortSignal
An AbortSignal to cancel the request.

​
Returns

​
CallToolResult
object
The result returned by the server tool.
​
content
ContentBlock[]
Array of content blocks returned by the tool (text, images, embedded resources, etc.).
​
structuredContent
Record<string, unknown>
Structured output if the tool defines an outputSchema. Parsed and validated by the server.
​
isError
boolean
true if the tool handler returned an error. When true, inspect content for error details. When false or absent, the call succeeded.

​
Usage

​
Basic tool call

const result = await app.callServerTool({
  name: "get_weather",
  arguments: { location: "Tokyo" },
});

if (result.isError) {
  console.error("Tool returned error:", result.content);
} else {
  console.log(result.structuredContent);
}

​
Using structured content

When the server tool defines an outputSchema, the parsed result is available on structuredContent: 
const result = await app.callServerTool({
  name: "list_products",
  arguments: { category: "electronics", limit: 10 },
});

if (!result.isError && result.structuredContent) {
  const products = result.structuredContent.items as Product[];
  renderProductList(products);
}

​
Cancelling a request

Pass an AbortSignal to cancel long-running tool calls: 
const controller = new AbortController();

const result = await app.callServerTool(
  { name: "generate_report", arguments: { year: 2025 } },
  { signal: controller.signal },
);

// Cancel from a UI button
cancelButton.addEventListener("click", () => controller.abort());
Tool-level execution errors are returned in the result with isError: true rather than throwing exceptions. Transport or protocol failures throw. Always check result.isError.