Let Claude call tools in your MCP App

​

Register an app tool in a view

• With a schema library: call app.registerTool
• With your own JSON Schema: set the onlisttools and oncalltool handlers

• registerAppTool: call it on your server to register the tool that opens the view
• app.registerTool: call it in the view to register an app tool

​

Register with app.registerTool and a schema library

• Schema library: for the input schema, pass a schema object from a library that implements Standard Schema with JSON Schema output, such as zod 4.2 or later
• SDK version: app.registerTool requires @modelcontextprotocol/ext-apps 1.7.0 or later
• Bundler: the sample imports both packages by name, which a browser can’t resolve, so bundle the view’s script. If your view loads the SDK from a CDN, as in the quickstart, register with handlers.

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

const app = new App({ name: "Shopping list", version: "1.0.0" });

app.registerTool(
  "add_item",
  {
    title: "Add item",
    description: "Add an item to the shopping list that is open in this view.",
    inputSchema: z.object({ name: z.string().describe("The item to add") })
  },
  async ({ name }) => {
    const item = document.createElement("li");
    item.textContent = name;
    document.querySelector("#items")?.append(item);
    return { content: [{ type: "text", text: "Added " + name + "." }] };
  }
);

await app.connect();

​

Register with handlers and your own JSON Schema

• onlisttools: return the tool definitions
• oncalltool: run each call. Check the arguments, because the handlers don’t validate them.
• App constructor: pass { tools: { listChanged: true } } as the second argument

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

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

app.onlisttools = async () => ({
  tools: [
    {
      name: "add_item",
      title: "Add item",
      description: "Add an item to the shopping list that is open in this view.",
      inputSchema: {
        type: "object",
        properties: { name: { type: "string", description: "The item to add" } },
        required: ["name"]
      }
    }
  ]
});

app.oncalltool = async ({ name, arguments: args }) => {
  if (name !== "add_item" || typeof args?.name !== "string") {
    return {
      content: [
        { type: "text", text: "Nothing was added. Call add_item with the item's name as a string." }
      ]
    };
  }
  const item = document.createElement("li");
  item.textContent = args.name;
  document.querySelector("#items")?.append(item);
  return { content: [{ type: "text", text: "Added " + args.name + "." }] };
};

await app.connect();

​

Test an app tool in Claude

1. Add your server to Claude as a custom connector
2. Start a new conversation with the unified Claude experience, which combines chat and Cowork. If the message box offers a choice of Chat or Cowork, your account doesn’t have it.
3. Set the permission setting in the message box to Manual. In Auto, Claude can use a tool without asking.
4. Ask Claude to open the app, and name your connector in the message
5. In a second message, ask for a change, such as adding milk to the list.

​

Check whether your organization has access to app tools

1. Test a tool in Claude
2. If Claude doesn’t ask you to approve the tool and doesn’t run it, rule out the causes under Claude finds no tools in the view
3. If none of those causes applies, your organization may not have access. Keep your app working without app tools, and test again later.

​

Update app tools while a view is open

• With app.registerTool: keep the handle that the function returns. Call enable(), disable(), update(), or remove() on that handle.
• To add a tool after connect(): call app.registerTool again
• With the onlisttools handler: call app.sendToolListChanged() when the list that the handler returns changes. app.sendToolListChanged requires @modelcontextprotocol/ext-apps 1.7.0 or later.

​

Design app tools

​

Approval before an app tool runs

• What the prompt names: the connector and the tool’s title. If you set no title, the user sees the name.
• What else the user can read: the values that Claude is sending, your description, and the tool’s inputs
• If the user declines: the tool isn’t called, and Claude receives an error result that says so
• Always allow: the prompt can offer this option, and Claude can then run that tool on later calls without asking

​

Keep each app tool definition constant

• A change to the tool’s name, title, description, or input schema
• A change to the server tool that opens the view

​

Write a complete first line for each tool description

​

Return text from app tools

• structuredContent: Claude reads it, as JSON, only when it receives no text at all from content
• Other block types: if you return a block of another type, such as an image, Claude receives text for that block too and doesn’t read the result’s structuredContent

​

Report a failure from an app tool

​

Limits on app tools

​

Views that Claude can reach

• Remote connector: the view must come from a remote connector. Claude doesn’t call the tools of a view from a local server, such as one in the Claude Desktop configuration file.
• Where to test: test on the web, in a conversation with the unified Claude experience.
  • On Team and Enterprise plans, an Owner or Primary Owner controls it with the Chat and Cowork unified setting in Organization settings > Capabilities.
• Loaded view: if the view isn’t loaded in the Claude page that the user has open, Claude’s call isn’t sent. Claude receives an error result that says so.
  • When a view loads again, it starts from your HTML, so store on your server anything that you need to keep.

​

Troubleshoot app tools

​

Claude finds no tools in the view

• You asked for the change in the message that opened the app: when the first view opens in a conversation, Claude receives its tools with your next message. Ask Claude to open the app, and name your connector in the message. Then ask for the change in a second message.
• You passed an inputSchema that isn’t a schema object:
  • Cause: app.registerTool can’t convert a plain object, such as JSON Schema or the { name: z.string() } shape that server tools take.
  • Effect: the view responds to tools/list with an error, and Claude can’t see the view’s other tools either.
  • Fix: pass a schema object from your schema library, or use the onlisttools and oncalltool handlers.
• The view exceeds a limit, or Claude can’t reach it: check the limits on app tools and the views that Claude can reach
• Your organization or conversation doesn’t have app tools: check whether your organization has access

​

app.registerTool is not a function

​

Client does not support tool capability

• Call app.registerTool for the first time after connect()
• Set onlisttools or oncalltool

​

Schema (vendor: zod) does not implement Standard JSON Schema (~standard.jsonSchema)

• Cause: with @modelcontextprotocol/ext-apps 2.x, the view responds to tools/list with this error when the schema comes from zod 4.1 or earlier
• Where it appears: in the view’s console at the Verbose level, in a line that starts with Sending message
• Fix: upgrade zod to 4.2 or later

​

Next steps

• Send messages to Claude from your MCP App: send Claude a request when the user acts in the view
• Supersede older widget instances: keep one copy of the app active when Claude opens it more than once
• Design guidelines: decide which interactions belong in the app and which in the conversation
• Troubleshoot MCP Apps: fix an app that doesn’t appear or loses its assets