build-mcp-app

Создание приложения MCP (интерактивные виджеты пользовательского интерфейса)

Приложение MCP — это стандартный сервер MCP, который также предоставляет ресурсы пользовательского интерфейса — интерактивные компоненты, отображаемые непосредственно в окне чата. Создайте приложение один раз, и оно будет работать в Claude, ChatGPT и любом другом хосте, реализующем интерфейс приложений.

Уровень пользовательского интерфейса является дополнительным. «Под капотом» по-прежнему используются те же инструменты, ресурсы и тот же сетевой протокол. Если вы ранее не создавали простой сервер MCP, build-mcp-server этот навык охватывает базовый уровень. Данный навык добавляет виджеты поверх него.

Тестирование в Claude: добавьте сервер в качестве пользовательского коннектора на claude.ai (через туннель Cloudflare для локальной разработки) — это позволит протестировать реальную песочницу iframe и hostContext. См. https://claude.com/docs/connectors/building/testing.

Особенности хоста Claude

• hostContext.safeAreaInsets: {top, right, bottom, left} (px) — соблюдайте эти значения для надрезов и наложения редактора.
• Для подачи каталога требуется OAuth или авторизация без учетной записи (none) — статический bearer доступен только при частном развертывании и блокирует появление в списке — плюс инструмент annotations и 3–5 скриншотов в формате PNG; см. references/directory-checklist.md.

Когда виджет превосходит простой текст

Не добавляйте пользовательский интерфейс просто так — большинству инструментов достаточно возвращать текст или JSON. Добавляйте виджет, если выполняется одно из следующих условий:

Если ни одно из этих условий не выполняется, откажитесь от виджета. Текст быстрее создаётся и быстрее отображается пользователю.

Виджеты против элицитации — выбирайте правильный путь

Прежде чем создавать виджет, проверьте, не покрывает ли это функции сбора данных. Сбор данных является неотъемлемой частью спецификации, не требует написания кода пользовательского интерфейса и работает в любом совместимом хосте.

Если это можно реализовать с помощью элицитации, используйте её. См. ../build-mcp-server/references/elicitation.md.

Архитектура: два варианта развертывания

Удаленное приложение MCP (наиболее распространенный вариант)

Размещённый сервер streamable-HTTP. Шаблоны виджетов предоставляются в качестве ресурсов; результаты работы инструментов ссылаются на них. Хост извлекает ресурс, отображает его в песочнице iframe и обеспечивает обмен сообщениями между виджетом и Claude.

┌──────────┐  tools/call   ┌────────────┐
│  Claude  │─────────────> │ MCP server │
│   host   │<── result ────│  (remote)  │
│          │  + widget ref │            │
│          │               │            │
│          │ resources/read│            │
│          │─────────────> │  widget    │
│ ┌──────┐ │<── template ──│  HTML/JS   │
│ │iframe│ │               └────────────┘
│ │widget│ │
│ └──────┘ │
└──────────┘

Приложение MCP, упакованное в MCPB (локальное + пользовательский интерфейс)

Тот же механизм работы виджетов, но сервер работает локально внутри пакета MCPB. Используйте этот вариант, когда виджету необходимо управлять локальным приложением — например, выбора файлов, просматривающего содержимое локального диска, или диалогового окна, управляющего настольным приложением.

Что касается механизмов упаковки MCPB, обратитесь к навыку «build-mcpb». Все, что описано ниже, применимо к обоим типам.

Как виджеты привязываются к инструментам

Инструмент с поддержкой виджетов имеет две отдельные регистрации:

1. Инструмент объявляет ресурс пользовательского интерфейса с помощью _meta.ui.resourceUri. Его обработчик возвращает простой текст/JSON — НЕ HTML.
2. Ресурс регистрируется отдельно и предоставляет HTML-код.

Когда Claude вызывает инструмент, хост видит _meta.ui.resourceUri, извлекает этот ресурс, отображает его в iframe и передаёт возвращаемое значение инструмента в iframe через событие ontoolresult события.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE }
  from "@modelcontextprotocol/ext-apps/server";
import { z } from "zod";const server = new McpServer({ name: "contacts", version: "1.0.0" });// 1. The tool — returns DATA, declares which UI to show
registerAppTool(server, "pick_contact", {
  description: "Open an interactive contact picker",
  annotations: { title: "Pick Contact", readOnlyHint: true },
  inputSchema: { filter: z.string().optional() },
  _meta: { ui: { resourceUri: "ui://widgets/contact-picker.html" } },
}, async ({ filter }) => {
  const contacts = await db.contacts.search(filter);
  // Plain JSON — the widget receives this via ontoolresult
  return { content: [{ type: "text", text: JSON.stringify(contacts) }] };
});// 2. The resource — serves the HTML
registerAppResource(
  server,
  "Contact Picker",
  "ui://widgets/contact-picker.html",
  {},
  async () => ({
    contents: [{
      uri: "ui://widgets/contact-picker.html",
      mimeType: RESOURCE_MIME_TYPE,
      text: pickerHtml,  // your HTML string
    }],
  }),
);

Схема URI ui:// определяется соглашением. Тип MIME ДОЛЖЕН быть RESOURCE_MIME_TYPE ("text/html;profile=mcp-app") — именно так хост понимает, что нужно отобразить его в виде интерактивного iframe, а не просто показать исходный код.

Среда выполнения виджета — App класс

Внутри iframe ваш скрипт взаимодействует с хостом через App класс из @modelcontextprotocol/ext-apps. Это постоянное двунаправленное соединение — виджет остается активным до тех пор, пока ведётся обмен данными: он получает новые результаты работы инструментов и отправляет действия пользователя.

<script type="module">
  /* ext-apps bundle inlined at build time → globalThis.ExtApps */
  /*__EXT_APPS_BUNDLE__*/
  const { App } = globalThis.ExtApps;  const app = new App({ name: "ContactPicker", version: "1.0.0" }, {});  // Set handlers BEFORE connecting
  app.ontoolresult = ({ content }) => {
    const contacts = JSON.parse(content[0].text);
    render(contacts);
  };  await app.connect();  // Later, when the user clicks something:
  function onPick(contact) {
    app.sendMessage({
      role: "user",
      content: [{ type: "text", text: `Selected contact: ${contact.id}` }],
    });
  }
script>

Параметр /*__EXT_APPS_BUNDLE__*/ заполнитель при запуске заменяется сервером содержимым @modelcontextprotocol/ext-apps/app-with-deps — см. references/iframe-sandbox.md , почему это необходимо, и фрагмент кода для переписания. Не import { App } from "https://esm.sh/..."; CSP iframe блокирует запросы на транзитивные зависимости, и виджет отображается пустым.

sendMessage — это типичный сценарий «пользователь что-то выбрал, сообщите об этом Клоду». updateModelContext предназначен для состояний, о которых Клод должен знать, но которые не должны загромождать чат. openLink требуется для любой навигации за пределы страницы — window.open а блокируются атрибутом sandbox.

Чего виджеты не могут делать:

• доступ к DOM, файлам cookie или хранилищу хост-страницы
• осуществлять сетевые запросы к произвольным источникам (ограничено CSP — направляйте через callServerTool)
• Открывать всплывающие окна или переходить по ссылкам напрямую — используйте app.openLink({url})
• Надежно загружать удаленные изображения — встроенные как data: URL-адресами на стороне сервера

Сделайте виджеты небольшими и одноцелевыми. Виджет выбора — для выбора. Диаграмма — для отображения. Не создавайте целое подприложение внутри iframe — разбейте его на несколько инструментов с специализированными виджетами.

Основа: минимальный виджет выбора

Установка:

npm install @modelcontextprotocol/sdk @modelcontextprotocol/ext-apps zod express

Сервер (src/server.ts):

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE }
  from "@modelcontextprotocol/ext-apps/server";
import express from "express";
import { readFileSync } from "node:fs";
import { createRequire } from "node:module";
import { z } from "zod";const require = createRequire(import.meta.url);
const server = new McpServer({ name: "contact-picker", version: "1.0.0" });// Inline the ext-apps browser bundle into the widget HTML.
// The iframe CSP blocks CDN script fetches — bundling is mandatory.
const bundle = readFileSync(
  require.resolve("@modelcontextprotocol/ext-apps/app-with-deps"), "utf8",
).replace(/export\{([^}]+)\};?\s*$/, (_, body) =>
  "globalThis.ExtApps={" +
  body.split(",").map((p) => {
    const [local, exported] = p.split(" as ").map((s) => s.trim());
    return `${exported ?? local}:${local}`;
  }).join(",") + "};",
);
const pickerHtml = readFileSync("./widgets/picker.html", "utf8")
  .replace("/*__EXT_APPS_BUNDLE__*/", () => bundle);registerAppTool(server, "pick_contact", {
  description: "Open an interactive contact picker. User selects one contact.",
  annotations: { title: "Pick Contact", readOnlyHint: true },
  inputSchema: { filter: z.string().optional().describe("Name/email prefix filter") },
  _meta: { ui: { resourceUri: "ui://widgets/picker.html" } },
}, async ({ filter }) => {
  const contacts = await db.contacts.search(filter ?? "");
  return { content: [{ type: "text", text: JSON.stringify(contacts) }] };
});registerAppResource(server, "Contact Picker", "ui://widgets/picker.html", {},
  async () => ({
    contents: [{ uri: "ui://widgets/picker.html", mimeType: RESOURCE_MIME_TYPE, text: pickerHtml }],
  }),
);const app = express();
app.use(express.json());
app.post("/mcp", async (req, res) => {
  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
  res.on("close", () => transport.close());
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});
app.listen(process.env.PORT ?? 3000);

Для приложений, использующих виджеты только локально (управление настольным приложением, чтение локальных файлов), замените транспорт на StdioServerTransport и упакуйте с помощью build-mcpb skill.

Виджет (widgets/picker.html):

html>
<meta charset="utf-8" />
<style>
  body { font: 14px system-ui; margin: 0; }
  ul { list-style: none; padding: 0; margin: 0; max-height: 300px; overflow-y: auto; }
  li { padding: 10px 14px; cursor: pointer; border-bottom: 1px solid #eee; }
  li:hover { background: #f5f5f5; }
  .sub { color: #666; font-size: 12px; }
style>
<ul id="list">ul>
<script type="module">
/*__EXT_APPS_BUNDLE__*/
const { App } = globalThis.ExtApps;
(async () => {
  const app = new App({ name: "ContactPicker", version: "1.0.0" }, {});
  const ul = document.getElementById("list");  app.ontoolresult = ({ content }) => {
    const contacts = JSON.parse(content[0].text);
    ul.innerHTML = "";
    for (const c of contacts) {
      const li = document.createElement("li");
      li.innerHTML = `
${c.name}
${c.email}
`;
      li.addEventListener("click", () => {
        app.sendMessage({
          role: "user",
          content: [{ type: "text", text: `Selected contact: ${c.id} (${c.name})` }],
        });
      });
      ul.append(li);
    }
  };  await app.connect();
})();
script>

См. references/widget-templates.md для ознакомления с дополнительными формами виджетов.

Рекомендации по проектированию, которые избавят вас от необходимости переделывать код

Один виджет на один инструмент. Не поддавайтесь соблазну создать один мега-виджет, который будет делать всё. Один инструмент → один специализированный виджет → одна чёткая форма результата. Клод гораздо лучше справляется с такими задачами.

В описании инструмента обязательно должен упоминаться виджет. При принятии решения о том, что вызвать, Клод видит только описание инструмента. Именно фраза «Открывает интерактивный выбор» в описании заставляет Клода выбрать именно этот инструмент, а не пытаться угадать его ID.

Виджеты не являются обязательными во время выполнения. Хосты, которые не поддерживают интерфейс приложений, просто игнорируют _meta.ui и отображают текстовое содержимое инструмента в обычном режиме. Поскольку ваш обработчик инструмента уже возвращает значимый текст/JSON (данные виджета), переход на альтернативный режим происходит автоматически — Claude видит данные напрямую, а не через виджет.

Не блокируйте процесс ожиданием результатов виджета для инструментов, предназначенных только для чтения. Виджет, который просто отображает данные (диаграмма, предварительный просмотр), не должен требовать действий пользователя для завершения работы. Возвращайте виджет отображения и текстовую сводку в одном результате, чтобы Claude мог продолжить рассуждения без ожидания.

Разветвляйте макет по количеству элементов, а не по количеству инструментов. Если один вариант использования — «показать один результат подробно», а другой — «показать много результатов рядом», не создавайте два инструмента — создайте один инструмент, который принимает items[], и позвольте виджету выбирать макет: items.length === 1 → подробный просмотр, > 1 → карусель. Это упрощает схему сервера и позволяет Claude естественным образом определять количество элементов.

Включите рассуждения Claude в полезную нагрузку. Короткое note поле для каждого элемента (почему Claude его выбрал), отображаемое в виде всплывающей подписи на карточке, предоставляет пользователям обоснование прямо в контексте выбора. Укажите это поле в описании инструмента, чтобы Claude его заполнял.

Нормализуйте формы изображений на стороне сервера. Если ваш источник данных возвращает изображения с сильно различающимися соотношениями сторон, преобразуйте их в предсказуемый вариант (например, с квадратными границами) перед извлечением для встроенного data-URL. Затем задайте контейнеру изображений виджета фиксированный aspect-ratio + object-fit: contain , чтобы всё располагалось по центру.

Следуйте теме хоста. app.getHostContext()?.theme (после connect()) плюс app.onhostcontextchanged для обновлений в реальном времени. Включайте и .dark класс , сохраняйте цвета в пользовательских свойствах CSS с помощью :root.dark {} блоком переопределения, установите color-scheme. Отключите mix-blend-mode: multiply в темном режиме — это приводит к исчезновению изображений.

Тестирование

Claude Desktop — текущие сборки по-прежнему требуют command/args конфигурационную форму (нет нативной "type": "http"). Оберните с помощью mcp-remote и принудительно http-only транспорт, чтобы SSE-проба не заглушала согласование возможностей виджетов:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:3000/mcp",
               "--allow-http", "--transport", "http-only"]
    }
  }
}

Desktop активно кэширует ресурсы пользовательского интерфейса. После редактирования HTML-кода виджета полностью закройте приложение (⌘Q / Alt+F4, а не просто окно) и перезапустите его, чтобы принудительно инициировать полную перезагрузку ресурсов.

Цикл JSON-RPC в режиме без графического интерфейса — быстрая итерация без перехода через Desktop:

# test.jsonl — one JSON-RPC message per line
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"t","version":"0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"your_tool","arguments":{...}}}(cat test.jsonl; sleep 10) | npx mcp-remote http://localhost:3000/mcp --allow-http

Функция sleep оставляет стандартный ввод (stdin) открытым достаточно долго, чтобы собрать все ответы. Проанализируйте вывод jsonl с помощью jq или однострочной командой на Python.

Цикл разработки виджетов — полностью избегайте цикла ⌘Q-перезапуск, предоставляя встроенный HTML-код виджета по простому GET-маршруту с помощью фиктивного ExtApps прослойкой, которая запускает ontoolresult по параметру запроса:

app.get("/widget-preview", (_req, res) => {
  const shim = `globalThis.ExtApps={applyHostStyleVariables:()=>{},App:class{
    constructor(){this.h={}} ontoolresult;onhostcontextchanged;
    async connect(){const p=new URLSearchParams(location.search).get("payload");
      if(p)this.ontoolresult?.({content:[{type:"text",text:p}]});}
    getHostContext(){return{theme:"light"}}
    sendMessage(m){console.log("sendMessage",m)} updateModelContext(){}
    callServerTool(){return Promise.resolve({content:[]})} openLink(){} downloadFile(){}
  }};`;
  res.type("html").send(widgetHtml.replace("/*__EXT_APPS_BUNDLE__*/", shim));
});

Откройте http://localhost:3000/widget-preview?payload={"rows":[...]} в обычной вкладке браузера и работайте с ним с помощью стандартных инструментов разработчика.

Резервный хост — используйте хост без интерфейса приложений (или MCP Inspector) и убедитесь, что текстовое содержимое инструмента корректно отображается даже при ухудшении условий.

Отладка CSP — откройте собственную консоль инструментов разработчика iframe. Нарушения CSP — главная причина, по которой виджеты незаметно выходят из строя (пустой прямоугольник, отсутствие ошибки в главной консоли). См. references/iframe-sandbox.md.

Справочные файлы

• references/iframe-sandbox.md — ограничения CSP/песочницы, шаблон встраивания пакетов, обработка изображений, стилизация хоста
• references/widget-templates.md — готовые HTML-шаблоны для выбора / подтверждения / индикатора прогресса / отображения
• references/apps-sdk-messages.md — App API классов: обмен сообщениями между виджетом ↔ хостом ↔ сервером, жизненный цикл и замена
• references/payload-budgeting.md — ограничения на размер результатов инструментов хоста, сначала обрезка, затем усечение, передача ресурсоемких данных через callServerTool
• references/abuse-protection.md — CIDR-диапазоны исходящего трафика Anthropic, многоуровневое ограничение скорости, trust proxy, кэширование ответов
• references/directory-checklist.md — предварительная проверка перед отправкой в каталог коннекторов