MCP Apps registerAppTool - Register UI Tools

MCP Apps SDK

import { registerAppTool } from '@modelcontextprotocol/ext-apps/server';

Overview

registerAppTool is a convenience wrapper around the MCP SDK’s server.registerTool() that normalizes UI metadata for compatibility across hosts. Use it instead of registerTool when your tool should render a View or when it needs MCP App visibility metadata. Use a runtime schema that supports Standard Schema validation and JSON Schema export. z.object() with Zod 4.2 or later meets both requirements. SDK 2.0 still accepts raw Zod shapes, but that overload is deprecated. See Tool Schemas for validation behavior and the SDK 2.0 migration guide.

Signature

function registerAppTool(
  server: McpServer,
  name: string,
  config: McpUiAppToolConfig,
  cb: ToolCallback
): RegisteredTool;

Parameters

McpServer

required

The MCP server instance.

string

required

Tool name/identifier.

McpUiAppToolConfig

required

Tool configuration. Extends the standard MCP ToolConfig with a required _meta field containing UI metadata.

string

Human-readable tool title.

string

Tool description for the model.

ZodRawShape | StandardSchemaWithJSON

Runtime schema for tool arguments. The recommended form implements Standard Schema validation and ~standard.jsonSchema; a raw Zod shape is deprecated. The SDK exports JSON Schema for tools/list and parses arguments before the callback runs.

ZodRawShape | StandardSchemaWithJSON

Runtime schema for successful structuredContent. The SDK exports JSON Schema for tools/list and validates successful results after the callback returns.

ToolAnnotations

Standard MCP tool annotations, such as readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. See Tool Annotations.

object

required

UI metadata linking this tool to a resource, controlling tool visibility, or both. See _meta Reference below for full details.

McpUiToolMeta

required

string

URI of the UI resource to display (e.g., "ui://weather/view.html"). Required for tools that render a View. Must match a URI registered via registerAppResource.

McpUiToolVisibility[]

Who can access this tool. Default: ["model", "app"]. See visibility below.

ToolCallback

required

Tool handler function. Receives parsed arguments and returns a CallToolResult.

Usage

Basic tool with UI

import { registerAppTool } from '@modelcontextprotocol/ext-apps/server';
import { z } from 'zod';

registerAppTool(
  server,
  'get-weather',
  {
    title: 'Get Weather',
    description: 'Get current weather for a location',
    inputSchema: z.object({ location: z.string() }),
    _meta: {
      ui: { resourceUri: 'ui://weather/view.html' },
    },
  },
  async (args) => {
    const weather = await fetchWeather(args.location);
    return {
      content: [{ type: 'text', text: JSON.stringify(weather) }],
      structuredContent: weather,
    };
  }
);

Read-only tool annotations

Add annotations when a UI tool is read-only, destructive, idempotent, or calls external systems. Hosts can use these hints for review UI and tool-calling behavior.

registerAppTool(
  server,
  'search-orders',
  {
    title: 'Search Orders',
    description: 'Search orders and display the results.',
    inputSchema: z.object({ query: z.string() }),
    annotations: {
      readOnlyHint: true,
      openWorldHint: false,
    },
    _meta: {
      ui: { resourceUri: 'ui://orders/view.html' },
    },
  },
  handler
);

App-only tool (hidden from model)

Set visibility: ["app"] for tools that should only be callable from the View, such as polling, pagination, or UI-driven server interactions. Omit resourceUri when the helper does not render a new View:

registerAppTool(
  server,
  'update-quantity',
  {
    description: 'Update item quantity in cart',
    inputSchema: z.object({ itemId: z.string(), quantity: z.number() }),
    _meta: {
      ui: {
        visibility: ['app'],
      },
    },
  },
  async ({ itemId, quantity }) => {
    const cart = await updateCartItem(itemId, quantity);
    return {
      content: [{ type: 'text', text: JSON.stringify(cart) }],
      structuredContent: cart,
    };
  }
);

Model-only tool

Set visibility: ["model"] for tools that the model can call but the View cannot:

registerAppTool(
  server,
  'show-cart',
  {
    description: "Display the user's shopping cart",
    _meta: {
      ui: {
        resourceUri: 'ui://shop/cart.html',
        visibility: ['model'],
      },
    },
  },
  async () => {
    const cart = await getCart();
    return { content: [{ type: 'text', text: JSON.stringify(cart) }] };
  }
);

`_meta` Reference

See Tool _meta for the complete reference on resourceUri, visibility, host behavior rules, and metadata normalization. See Tool Annotations for when to set readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. See Tool and Resource Contract for how tool metadata, resource metadata, content, and structuredContent fit together. See Tool Schemas for inputSchema, outputSchema, runtime validation, Standard Schema requirements, and common errors.

In the sunpeak framework, tools are defined as auto-discovered files. See the Tool File Reference.

Overview

App

MCP

React

Server

Styling

Types

MCP Apps registerAppTool - Register UI Tools

Overview

Signature

Parameters

Usage

Basic tool with UI

Read-only tool annotations

App-only tool (hidden from model)

Model-only tool

`_meta` Reference

​Overview

​Signature

​Parameters

​Usage

​Basic tool with UI

​Read-only tool annotations

​App-only tool (hidden from model)

​Model-only tool

​_meta Reference

Overview

Signature

Parameters

Usage

Basic tool with UI

Read-only tool annotations

App-only tool (hidden from model)

Model-only tool

`_meta` Reference