← Все гайды AI Release
EN Подписаться на @ai_release1

Пошаговое руководство: как создать MCP App с интерактивным интерфейсом и подключить его к ИИ-агенту

Обновлено: 20.11.2026 · AI Release · @ai_release1
Пошаговое руководство: как создать MCP App с интерактивным интерфейсом и подключить его к ИИ-агенту

TL;DR

Требования и подготовка

Иллюстрация к разделу «Требования и подготовка»
Иллюстрация к разделу «Требования и подготовка»

Про точные имена методов протокола и место поля _meta в описании инструмента: в постах канала этих данных нет, в гайде они помечены как «сверьтесь с документацией». Код ниже — рабочая структура; сверяйте с актуальной спецификацией расширения.

Шаг 1. Каркас MCP-сервера и первый инструмент

Что сделать: создать проект, установить SDK, написать сервер, который по stdio отдаёт один инструмент.

Зачем: пока сервер не отвечает на initialize и tools/list, клиенту нечего подключать — интерфейс строить рано.

mkdir demo-mcp-app && cd demo-mcp-app
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript tsx
npx tsc --init --module nodenext --target es2022 --outDir dist
mkdir -p src ui

server.ts в папке src:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "demo-mcp-app", version: "0.1.0" });

server.registerTool(
  "show_order",
  {
    title: "Показать заказ",
    description: "Возвращает данные заказа и открывает интерактивную панель",
    inputSchema: { orderId: z.string() },
  },
  async ({ orderId }) => ({
    content: [{ type: "text", text: `Заказ ${orderId}: 2 позиции, 4200 RUB` }],
    structuredContent: { orderId, items: 2, total: 4200, currency: "RUB" },
  })
);

await server.connect(new StdioServerTransport());

Сборка и ручной вызов:

npm run build
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"<версия-из-спецификации>","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}' | node dist/server.js

Как проверить: в stdout придёт JSON-RPC ответ с "result", внутри — "serverInfo": { "name": "demo-mcp-app" }. Если stdout пуст, а в stderr текст ошибки — сервер упал на импорте.

Почему это работает: клиент запускает node dist/server.js как дочерний процесс и обменивается с ним строками JSON — отдельный порт и HTTP не нужны.

Шаг 2. Интерактивный UI-ресурс и привязка к инструменту

Иллюстрация к разделу «Шаг 2. Интерактивный UI-ресурс и привязка к инструменту»
Иллюстрация к разделу «Шаг 2. Интерактивный UI-ресурс и привязка к инструменту»

Что сделать: положить HTML-панель в ui/panel.html, зарегистрировать её как ресурс с URI ui://demo/panel.html и сослаться на этот URI в метаданных инструмента.

Зачем: MCP-клиент сам по себе рисует только текст. Чтобы вместо строки появилась кнопка, сервер должен отдать ресурс и явно сказать: «вызов этого инструмента обслуживает вот этот UI».

Регистрация ресурса добавляется в server.ts:

import { readFileSync } from "node:fs";

const PANEL_URI = "ui://demo/panel.html";

server.registerResource(
  "panel",
  PANEL_URI,
  { mimeType: "text/html;profile=mcp-app", title: "Панель заказа" },
  async () => ({
    contents: [{
      uri: PANEL_URI,
      mimeType: "text/html;profile=mcp-app",
      text: readFileSync(new URL("../ui/panel.html", import.meta.url), "utf8"),
    }],
  })
);

ui/panel.html — минимальная панель, которая получает данные инструмента и отправляет сообщение в диалог:

<!doctype html>
<html lang="ru">
<head><meta charset="utf-8"><title>Заказ</title></head>
<body>
  <h1>Заказ</h1>
  <p id="total">—</p>
  <button id="confirm">Подтвердить</button>
  <script>
    const host = window.parent; // хост-клиент = родительское окно iframe
    host.postMessage({ jsonrpc: "2.0", id: 1, method: "ui/initialize", params: {} }, "*");

    window.addEventListener("message", (e) => {
      const msg = e.data;
      if (msg && msg.method === "ui/notifications/tool-result") {
        const d = msg.params.structuredContent;
        document.getElementById("total").textContent = d.items + " поз. на " + d.total + " " + d.currency;
      }
    });

    document.getElementById("confirm").onclick = () => {
      host.postMessage({
        jsonrpc: "2.0", method: "ui/message",
        params: { role: "user", content: [{ type: "text", text: "Заказ подтверждён" }] }
      }, "*");
    };
  </script>
</body>
</html>

Метаданные инструмента (как это выглядит в ответе на tools/list — сверьте расположение _meta со спецификацией вашей версии):

{
  "name": "show_order",
  "description": "Возвращает данные заказа и открывает интерактивную панель",
  "inputSchema": { "type": "object", "properties": { "orderId": { "type": "string" } }, "required": ["orderId"] },
  "_meta": { "ui": { "resourceUri": "ui://demo/panel.html" } }
}

Пример: вызов инструмента с {"orderId":"A-1043"} должен вернуть structuredContent с items: 2, total: 4200, и панель показывает «2 поз. на 4200 RUB».

Как проверить: запустить инспектор и посмотреть список ресурсов и инструментов:

npx @modelcontextprotocol/inspector node dist/server.js

В консоли появится адрес вида http://localhost:<порт>/?... — откройте его, вкладка Resources должна содержать ui://demo/panel.html, вкладка Tools — show_order. Почему это работает: инспектор — обычный MCP-клиент, он видит ровно то же, что увидит агент.

Шаг 3. Подключение к ИИ-агенту и проверка end-to-end

Иллюстрация к разделу «Шаг 3. Подключение к ИИ-агенту и проверка end-to-end»
Иллюстрация к разделу «Шаг 3. Подключение к ИИ-агенту и проверка end-to-end»

Что сделать: прописать сервер в конфиг клиента и вызвать инструмент из чата.

Зачем: до этого сервер проверялся отдельно; теперь нужно убедиться, что агент запускает процесс сам, получает описание инструмента и передаёт данные в панель.

Конфиг клиента (пример для формата mcpServers; путь к файлу настроек зависит от клиента и ОС — сверьтесь с документацией):

{
  "mcpServers": {
    "demo-app": {
      "command": "node",
      "args": ["/абсолютный/путь/до/demo-mcp-app/dist/server.js"]
    }
  }
}

Получить абсолютный путь:

cd demo-mcp-app && pwd

Пример запроса агенту: «Покажи заказ A-1043». Ожидаемый результат на экране: текстовый ответ «Заказ A-1043: 2 позиции, 4200 RUB» и под ним интерактивная панель с кнопкой «Подтвердить»; нажатие кнопки добавляет в диалог сообщение «Заказ подтверждён».

Чек-лист приёмки:

Если нужен второй, «постоянный» навык для агента — см. как создать Claude Skill; MCP App удобнее там, где нужен живой интерфейс, а Skill — там, где достаточно инструкции и файлов.

Возможные проблемы и решения

Проблема. Клиент пишет, что сервер отключился, инструментов нет

Проблема. В чате только текст, панель не появляется

Проблема. Агент не может запустить процесс

Резюме и следующие шаги

Вы получили MCP-сервер с инструментом show_order, HTML-панель, отдаваемую как UI-ресурс, и подключение к агенту с проверкой по чек-листу. Дальше расширяйте панель: добавляйте вызовы tools/call из интерфейса и передачу выбранных пользователем параметров обратно в модель.

FAQ

Чем MCP App отличается от обычного MCP-сервера?

Обычный сервер возвращает текст и данные, а MCP App дополнительно отдаёт HTML-ресурс с mimeType вида text/html;profile=mcp-app и связывает его с инструментом, поэтому клиент рисует интерактивную панель.

Нужен ли отдельный веб-сервер и хостинг для интерфейса?

Нет: HTML лежит файлом в проекте и отдаётся через resources/read. Хостинг понадобится только если данные для панели приходят из внешнего API — тогда см. как подключить ИИ к домашнему серверу.

Можно ли обойтись без TypeScript?

Да, SDK существует и для других языков; набор поддерживаемых языков и точные имена пакетов сверьтесь с документацией.

Безопасно ли, что интерфейс общается с чатом через postMessage?

Панель живёт в песочнице iframe и не имеет прямого доступа к приложению: все действия идут сообщениями, которые хост может отфильтровать. Конкретные ограничения песочницы зависят от клиента — сверьтесь с его документацией.

🤖 Кратко для ИИ

AI Release Knowledge Layer
Машинно-читаемое описание публикации · Версия 1.0

Статус: практическое руководство. Часть утверждений — заявления вендоров и проектов; проверяйте на своей среде.

1. Суть публикации

Пошаговая инструкция: собираем MCP App с собственным интерфейсом, описываем инструменты и ресурсы, подключаем к Claude Desktop и проверяем работу в диалоге с агентом. Время выполнения: 45–60 минут Уровень сложности: Intermediate

Внутри: прямые ответы, ключевые факты, участники, связи, достоверность, неизвестное и источники.

Машинные данные публикации: Citation Map JSON · JSON-LD · Semantic Embeddings — отдельный этап.

Полный Knowledge Layer: разделы 2–8

2. Прямые ответы

Что это за материал?
Пошаговая инструкция: собираем MCP App с собственным интерфейсом, описываем инструменты и ресурсы, подключаем к Claude Desktop и проверяем работу в диалоге с агентом. → подробнее (AR-GUIDE-POSHAGOVOE-001)
Что понадобится?
ОС: Windows 10/11, macOS или Linux — команды ниже даны для bash, различия для PowerShell отмечены.; Node.js LTS + npm: проверить node -v и npm -v.; Права на запись в папку проекта (не в Program Files и не в C:\Windows).; MCP-клиент (Claude Desktop, VS Code или другой): должен уметь показывать UI-ресурсы, а не только… → подробнее (AR-GUIDE-POSHAGOVOE-003)
Как это сделать?
Шаг 1. Каркас MCP-сервера и первый инструмент → Шаг 2. Интерактивный UI-ресурс и привязка к инструменту → Шаг 3. Подключение к ИИ-агенту и проверка end-to-end → подробнее (AR-GUIDE-POSHAGOVOE-004)
Что может пойти не так?
Ошибка: Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/абсолютный/путь/до/demo-mcp-app/dist/server.js' → подробнее (AR-GUIDE-POSHAGOVOE-006)

3. Ключевые факты

  1. Время выполнения: 45–60 минут — подтверждение; статус: заявление источника.
  2. Уровень сложности: Intermediate — подтверждение; статус: заявление источника.
  3. Понадобится: Node.js LTS и npm (точные номера версий в постах канала не приводятся — сверьтесь с документацией), пакет @modelcontextprotocol/sdk, MCP-клиент с поддержкой расширения MCP Apps (интерфейсов внутри чата), редактор кода, терминал. — подтверждение; статус: заявление источника.
  4. ОС: Windows 10/11, macOS или Linux — команды ниже даны для bash, различия для PowerShell отмечены. — подтверждение; статус: заявление источника.
  5. Node.js LTS + npm: проверить node -v и npm -v. — подтверждение; статус: заявление источника.
  6. Права на запись в папку проекта (не в Program Files и не в C:\Windows). — подтверждение; статус: заявление источника.
  7. Ошибка: Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/абсолютный/путь/до/demo-mcp-app/dist/server.js' — подтверждение; статус: анализ AI Release.
  8. Причина: TypeScript не собран в dist, либо в конфиге указан путь до src. — подтверждение; статус: анализ AI Release.

4. Участники и сущности

СущностьТипРоль в публикации
MCP Appsтема/инструментупоминается в заголовке, TL;DR или разделах гайда
как создать MCP Appтема/инструментупоминается в заголовке, TL;DR или разделах гайда
MCP сервер с интерфейсомтема/инструментупоминается в заголовке, TL;DR или разделах гайда
MCP UI extensionтема/инструментупоминается в заголовке, TL;DR или разделах гайда
подключить MCP App к Claudeтема/инструментупоминается в заголовке, TL;DR или разделах гайда
Windowsплатформа/технологияупоминается в заголовке, TL;DR или разделах гайда
Linuxплатформа/технологияупоминается в заголовке, TL;DR или разделах гайда
macOSплатформа/технологияупоминается в заголовке, TL;DR или разделах гайда
Node.jsплатформа/технологияупоминается в заголовке, TL;DR или разделах гайда
npmплатформа/технологияупоминается в заголовке, TL;DR или разделах гайда

5. Связи и контекст

  • Гайд — описывает → Пошаговое руководство: как создать MCP App с интерактивным интерфейсом и подключить его к ИИ-агенту (AR-GUIDE-POSHAGOVOE-001).
  • Гайд — содержит шаг → Шаг 1. Каркас MCP-сервера и первый инструмент (AR-GUIDE-POSHAGOVOE-001).

6. Достоверность и происхождение информации

Подтверждено

В материале нет отдельного независимого подтверждения; ниже разделены заявления источников и редакционные выводы.

Заявление источника

  • Характеристики продуктов, версии, цены и лимиты — из описаний вендоров и материалов гайда.
  • Команды и шаги приведены как рекомендация, а не как гарантированный результат.

Анализ AI Release

  • Структура, сравнение и критерии выбора — редакционные.
  • Гайд не заменяет независимый аудит или юридическую консультацию.

7. Что пока неизвестно

  • Ошибка: Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/абсолютный/путь/до/demo-mcp-app/dist/server.js'
  • Причина: TypeScript не собран в dist, либо в конфиге указан путь до src.
  • Решение: cd demo-mcp-app && npm run build && ls dist/server.js — файл должен существовать; путь в конфиге должен заканчиваться на dist/server.js.
  • Ошибка: resources/read: unknown resource uri ui://demo/panel.html

8. Источники

ИсточникТипРоль
Внешние ссылки в материале не указаны——

Как цитировать: AI Release. Пошаговое руководство: как создать MCP App с интерактивным интерфейсом и подключить его к ИИ-агенту. ai-release.org.