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.

Signature

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

Parameters

server

McpServer

required

The MCP server instance.

name

string

required

Tool name/identifier.

config

McpUiAppToolConfig

required

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

title

string

Human-readable tool title.

description

string

Tool description for the model.

inputSchema

ZodRawShape | AnySchema

Zod schema or JSON Schema for tool arguments.

outputSchema

ZodRawShape | AnySchema

Zod schema or JSON Schema for tool output.

annotations

ToolAnnotations

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

_meta

object

required

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

McpUiToolMeta

required

resourceUri

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.

visibility

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: { 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: { 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: { 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.

In the sunpeak framework, tools are defined as auto-discovered files. See the Tool File 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