MCP Apps callServerTool - Call Server-Side Tools

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

object

required

The tool call parameters.

string

required

The name of the server tool to call. Must match a tool registered on the MCP server.

Record<string, unknown>

Arguments to pass to the tool. The shape must match the tool’s inputSchema. Omit if the tool takes no arguments.

RequestOptions

Optional request configuration.

AbortSignal

An AbortSignal to cancel the request.

Returns

object

The result returned by the server tool.

ContentBlock[]

Array of content blocks returned by the tool (text, images, embedded resources, etc.).

Record<string, unknown>

Structured output if the tool defines an outputSchema. Parsed and validated by the server.

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.

Requests overview — all available View-to-host request methods
useCallServerTool — sunpeak React convenience hook
registerAppTool — register tools on the server with UI metadata
Tool _meta — visibility and metadata configuration

Overview

App

MCP

React

Server

Styling

Types

MCP Apps callServerTool - Call Server-Side Tools

Overview

Signature

Parameters

Returns

Usage

Basic tool call

Using structured content

Cancelling a request

​Overview

​Signature

​Parameters

​Returns

​Usage

​Basic tool call

​Using structured content

​Cancelling a request

​Related

Overview

Signature

Parameters

Returns

Usage

Basic tool call

Using structured content

Cancelling a request

Related