@modelcontextprotocol/sdk, MCP-клиент с поддержкой расширения MCP Apps (интерфейсов внутри чата), редактор кода, терминал.
node -v и npm -v.Program Files и не в C:\Windows).Про точные имена методов протокола и место поля _meta в описании инструмента: в постах канала этих данных нет, в гайде они помечены как «сверьтесь с документацией». Код ниже — рабочая структура; сверяйте с актуальной спецификацией расширения.
Что сделать: создать проект, установить 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 не нужны.

Что сделать: положить 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-клиент, он видит ровно то же, что увидит агент.

Что сделать: прописать сервер в конфиг клиента и вызвать инструмент из чата.
Зачем: до этого сервер проверялся отдельно; теперь нужно убедиться, что агент запускает процесс сам, получает описание инструмента и передаёт данные в панель.
Конфиг клиента (пример для формата 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» и под ним интерактивная панель с кнопкой «Подтвердить»; нажатие кнопки добавляет в диалог сообщение «Заказ подтверждён».
Чек-лист приёмки:
show_order виден в списке инструментов агента.Если нужен второй, «постоянный» навык для агента — см. как создать Claude Skill; MCP App удобнее там, где нужен живой интерфейс, а Skill — там, где достаточно инструкции и файлов.
Проблема. Клиент пишет, что сервер отключился, инструментов нет
Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/абсолютный/путь/до/demo-mcp-app/dist/server.js'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_meta.ui.resourceUri не совпадает с зарегистрированным (опечатка, разный регистр, лишний слэш).grep -n "ui://" src/server.ts; в выводе должны быть ровно две одинаковые строки, затем npm run build и перезапуск клиента.Проблема. Агент не может запустить процесс
spawn node ENOENTnode не находится.which node (macOS/Linux) или where node (PowerShell) и подставить абсолютный путь в поле "command".Вы получили MCP-сервер с инструментом show_order, HTML-панель, отдаваемую как UI-ресурс, и подключение к агенту с проверкой по чек-листу. Дальше расширяйте панель: добавляйте вызовы tools/call из интерфейса и передачу выбранных пользователем параметров обратно в модель.
Чем MCP App отличается от обычного MCP-сервера?
Обычный сервер возвращает текст и данные, а MCP App дополнительно отдаёт HTML-ресурс с mimeType вида text/html;profile=mcp-app и связывает его с инструментом, поэтому клиент рисует интерактивную панель.
Нужен ли отдельный веб-сервер и хостинг для интерфейса?
Нет: HTML лежит файлом в проекте и отдаётся через resources/read. Хостинг понадобится только если данные для панели приходят из внешнего API — тогда см. как подключить ИИ к домашнему серверу.
Можно ли обойтись без TypeScript?
Да, SDK существует и для других языков; набор поддерживаемых языков и точные имена пакетов сверьтесь с документацией.
Безопасно ли, что интерфейс общается с чатом через postMessage?
Панель живёт в песочнице iframe и не имеет прямого доступа к приложению: все действия идут сообщениями, которые хост может отфильтровать. Конкретные ограничения песочницы зависят от клиента — сверьтесь с его документацией.
Статус: практическое руководство. Часть утверждений — заявления вендоров и проектов; проверяйте на своей среде.
Пошаговая инструкция: собираем MCP App с собственным интерфейсом, описываем инструменты и ресурсы, подключаем к Claude Desktop и проверяем работу в диалоге с агентом. Время выполнения: 45–60 минут Уровень сложности: Intermediate
Машинные данные публикации: Citation Map JSON · JSON-LD · Semantic Embeddings — отдельный этап.
| Сущность | Тип | Роль в публикации |
|---|---|---|
| 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 или разделах гайда |
В материале нет отдельного независимого подтверждения; ниже разделены заявления источников и редакционные выводы.
| Источник | Тип | Роль |
|---|---|---|
| Внешние ссылки в материале не указаны | — | — |
Как цитировать: AI Release. Пошаговое руководство: как создать MCP App с интерактивным интерфейсом и подключить его к ИИ-агенту. ai-release.org.