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

> AI Release · @ai_release1 · https://ai-release.org/guides/poshagovoe-rukovodstvo-kak-sozdat-mcp-app-s-interaktivn.html

## TL;DR
- Время выполнения: 45–60 минут
- Уровень сложности: Intermediate
- Понадобится: Node.js LTS и npm (точные номера версий в постах канала не приводятся — сверьтесь с документацией), пакет `@modelcontextprotocol/sdk`, MCP-клиент с поддержкой расширения MCP Apps (интерфейсов внутри чата), редактор кода, терминал.

## Требования и подготовка
![Иллюстрация к разделу «Требования и подготовка»](https://ai-release.org/guides/img/poshagovoe-rukovodstvo-kak-sozdat-mcp-app-s-interaktivn-ru-1.jpg?v=1795164147)

- ОС: 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-ресурсы, а не только текст. Поддержка расширения MCP Apps зависит от версии клиента — сверьтесь с документацией клиента.
- Терминология: MCP (Model Context Protocol) — открытый протокол, по которому ИИ-клиент общается с внешним сервером инструментов; транспорт stdio — обмен JSON-RPC сообщениями через стандартный ввод/вывод процесса; UI-ресурс — HTML-файл, который сервер отдаёт клиенту для отрисовки в песочнице (iframe).

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

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

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

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

```bash
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`:

```ts
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());
```

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

```bash
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-ресурс и привязка к инструменту»](https://ai-release.org/guides/img/poshagovoe-rukovodstvo-kak-sozdat-mcp-app-s-interaktivn-ru-2.jpg?v=1795164153)


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

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

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

```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` — минимальная панель, которая получает данные инструмента и отправляет сообщение в диалог:

```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` со спецификацией вашей версии):

```json
{
  "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».

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

```bash
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»](https://ai-release.org/guides/img/poshagovoe-rukovodstvo-kak-sozdat-mcp-app-s-interaktivn-ru-3.jpg?v=1795164162)


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

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

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

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

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

```bash
cd demo-mcp-app && pwd
```

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

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

- [ ] Процесс сервера стартует без ошибок в логах клиента.
- [ ] `show_order` виден в списке инструментов агента.
- [ ] После вызова появляется панель, а не только текст.
- [ ] Кнопка в панели отправляет сообщение в диалог.

Если нужен второй, «постоянный» навык для агента — см. [как создать Claude Skill](https://ai-release.org/guides/kak-sozdat-claude-skill-poshagovoe-rukovodstvo-po-svoim.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide); MCP App удобнее там, где нужен живой интерфейс, а Skill — там, где достаточно инструкции и файлов.

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

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

- Ошибка: `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`
- Причина: URI в `_meta.ui.resourceUri` не совпадает с зарегистрированным (опечатка, разный регистр, лишний слэш).
- Решение: сравнить оба места — `grep -n "ui://" src/server.ts`; в выводе должны быть ровно две одинаковые строки, затем `npm run build` и перезапуск клиента.

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

- Ошибка: `spawn node ENOENT`
- Причина: GUI-приложение не видит PATH терминала, `node` не находится.
- Решение: `which node` (macOS/Linux) или `where node` (PowerShell) и подставить абсолютный путь в поле `"command"`.

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

## FAQ

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

**Нужен ли отдельный веб-сервер и хостинг для интерфейса?**
Нет: HTML лежит файлом в проекте и отдаётся через `resources/read`. Хостинг понадобится только если данные для панели приходят из внешнего API — тогда см. [как подключить ИИ к домашнему серверу](https://ai-release.org/guides/kak-podklyuchit-ii-k-domashnemu-serveru-poshagovoe-ruko.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide).

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

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