--- title: Подключение к MCP description: Пошаговое подключение агента к MCP — эндпоинт, трёхшаговый JSON-RPC handshake полными curl-командами, auth-заголовок и таблица «симптом → причина → действие». locale: ru version: 0.2.0 canonical: https://enterium-developer-docs.pages.dev/developers/ru/mcp/connecting/ --- > Documentation index: https://enterium-developer-docs.pages.dev/developers/llms.txt — every page of this portal has a Markdown twin at .md; the frozen API contract is at https://enterium-developer-docs.pages.dev/developers/api/openapi.json. Платформа экспонирует MCP-сервер поверх **Streamable HTTP** (JSON-RPC). Страница написана для агентов любой силы: выполняй шаги буквально и по порядку. Каждая команда полная — ничто не предполагается извне. ## Факты, которые понадобятся | Факт | Значение | | --- | --- | | Эндпоинт | `https://entherium.duckdns.org:8443/mcp/` | | Транспорт | MCP Streamable HTTP (JSON-RPC поверх POST; ответы — SSE) | | Auth | `Authorization: Bearer ` на **каждом** запросе | | Discovery без auth | `GET /mcp-info` (страница онбординга), `GET /llms.txt` | | Что получаешь | 14 тулов + 5 ресурсов ([полный справочник](../tools/)) | | Read-only mount | `https://entherium.duckdns.org:8443/mcp/readonly/` — тот же токен, только 7 читающих тулов ([зачем](#read-only-mount)) | | Docs MCP, **без токена** | `https://entherium.duckdns.org:8443/mcp/docs/` — эта документация как `search` / `fetch` / `submit_feedback` ([подробнее](#docs-mcp-без-токена)) | ## Предусловия - Есть агент-токен (`` ниже). Без него каждый вызов вернёт `401` — сначала запроси токен у владельца платформы. - Твой HTTP-клиент умеет POST с кастомными заголовками и читает тело как текст. Ответы приходят как Server-Sent Events: бери строки, начинающиеся с `data: `, и парси остаток строки как JSON. ## Шаг 1 — инициализируй сессию ```sh curl -sS -D headers.txt https://entherium.duckdns.org:8443/mcp/ \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}}}' ``` Ожидается: SSE-тело, в чьей `data:`-строке есть `"serverInfo"`, и заголовок ответа **`mcp-session-id`** в `headers.txt`. Скопируй его — это `` для следующих шагов. Получил `401` — токен отсутствует или истёк, см. таблицу ниже. Не иди дальше, пока шаг не вернёт 200. ## Шаг 2 — подтверди инициализацию ```sh curl -sS https://entherium.duckdns.org:8443/mcp/ \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "mcp-session-id: " \ -d '{"jsonrpc":"2.0","method":"notifications/initialized"}' ``` Ожидается: HTTP 2xx с пустым или тривиальным телом. Шаг обязателен — без него часть клиентов падает на последующих вызовах. ## Шаг 3 — первый вызов тула Всегда начинай с `start_here`: он возвращает упорядоченный план работы с платформой и capability-версию read-поверхности. ```sh curl -sS https://entherium.duckdns.org:8443/mcp/ \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "mcp-session-id: " \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"start_here","arguments":{}}}' ``` Ожидается: `data:`-строка с JSON плана. Дальше — по [справочнику тулов](../tools/): каждая страница тула показывает точный payload его `tools/call`. ## Подключение из клиента одним шагом Три curl-шага выше — то, что любой клиент делает под капотом. Клиенту достаточно URL и заголовка: **Claude Code** ```sh claude mcp add --transport http enterium https://entherium.duckdns.org:8443/mcp/readonly/ \ --header "Authorization: Bearer " ``` **Cursor / VS Code / любой клиент с `mcp.json`** ```json { "mcpServers": { "enterium": { "url": "https://entherium.duckdns.org:8443/mcp/readonly/", "headers": { "Authorization": "Bearer " } } } } ``` Замените `readonly/` на `/mcp/` только когда действительно нужны пишущие тулы. Для docs-сервера без токена ссылки установки работают как есть: [Добавить в Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=enterium-docs&config=eyJ1cmwiOiJodHRwczovL2VudGhlcml1bS5kdWNrZG5zLm9yZzo4NDQzL21jcC9kb2NzLyJ9) · [Добавить в VS Code](vscode:mcp/install?%7B%22name%22%3A%22enterium-docs%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fentherium.duckdns.org%3A8443%2Fmcp%2Fdocs%2F%22%7D) · Claude Code: `claude mcp add --transport http enterium-docs https://entherium.duckdns.org:8443/mcp/docs/`. ## Read-only mount `/mcp/readonly/` отдаёт тот же сервер без пишущих тулов: перечислены только инструменты с `readOnlyHint: true`, а вызов пишущего по имени завершается ошибкой. Тот же bearer-токен, то же рукопожатие, тот же `start_here`. Используйте его по умолчанию для оценки, для исследовательских ассистентов и для любого клиента, который не должен случайно завести тикет или сдвинуть задачу — выбор делается URL'ом, а не доверием к тому, что клиент уважает подсказки. Полный сервер остаётся на `/mcp/`. ## Docs MCP без токена `/mcp/docs/` превращает эту документацию в три инструмента и **не требует токена**: | Инструмент | Что делает | | --- | --- | | `search(query, limit)` | Ранжирует страницы портала по запросу; возвращает `{results: [{id, title, url}]}` — `id` это маршрут страницы | | `fetch(id)` | Возвращает страницу как Markdown (`{id, title, text, url, metadata}`) — `.md`-двойник, меньше токенов, чем HTML | | `submit_feedback(page, message)` | Отправляет предложение команде документации; анонимно, не более 5 в час с адреса; сначала спрашивает пользователя | Имена и формы инструментов следуют контракту deep-research коннекторов, поэтому сервер можно добавить в ChatGPT или Claude как коннектор без изменений. Он не читает и не пишет данные платформы — всё берётся из опубликованного портала, — поэтому и стоит вне токен-гейта. ## Если не работает | Симптом | Причина | Действие | | --- | --- | --- | | `401` на простом браузерном `GET /mcp/` | Auth проверяется на маунте, до согласования формата — без токена до транспорта не добраться | Ожидаемо. В браузере смотреть нечего; страница для людей — `GET /mcp-info` | | `406 Not Acceptable` на `GET /mcp/` **с** токеном | Это не браузерный URL; сервер требует JSON-RPC handshake | Три шага выше или библиотека MCP-клиента | | `401` на **каждом** вызове | Токен отсутствует, битый или истёк (auth проверяется на маунте, до любого тула) | Токены выпускает владелец платформы (`POST /api/v1/auth/agent-token` — только суперпользователь) — попроси перевыпуск. ⚠️ Новый токен **заменяет** грант-пул — перепроверь `my_capabilities` | | `403` или capability-ошибка внутри результата тула | Токен валиден, но запись вне пула или нет capability | Позови `my_capabilities`; запроси недостающий грант у владельца | | Список тулов внезапно пуст после деплоя платформы | Деплой перезапустил api-контейнер и убил твою живую MCP-сессию; сессии не восстанавливаются | Повтори handshake с шага 1 (новый `mcp-session-id`) | | Тело ответа нечитаемо | Ты читаешь сырой SSE | Парси только строки с `data: `; склеивай многострочные события перед JSON-парсом | | `307` на `/mcp` (без слэша) | Транспорт живёт на `/mcp/`; сервер редиректит | Сразу `/mcp/` — не все клиенты следуют редиректу на POST | ## Два правила чтения, спасающие агентов 1. **Читай значения payload, а не схемы.** Поясняющий контекст живёт в самих JSON-ответах (например, заметки о статусе внутри данных) — платформа кладёт смысл в payload, потому что многие агенты никогда не интроспектируют описания тулов. 2. **Перепроверяй `start_here` после апгрейдов.** Передавай кэшированную `capability_version` как `last_seen_version`; если поверхность изменилась, ответ перечислит, что принять к сведению до действий.