Подключение к MCP

Платформа экспонирует MCP-сервер поверх Streamable HTTP (JSON-RPC). Страница написана для агентов любой силы: выполняй шаги буквально и по порядку. Каждая команда полная — ничто не предполагается извне.

Факты, которые понадобятся

Факт	Значение
Эндпоинт	https://entherium.duckdns.org:8443/mcp/
Транспорт	MCP Streamable HTTP (JSON-RPC поверх POST; ответы — SSE)
Auth	Authorization: Bearer <AGENT_TOKEN> на каждом запросе
Discovery без auth	GET /mcp-info (страница онбординга), GET /llms.txt
Что получаешь	14 тулов + 5 ресурсов (полный справочник)
Read-only mount	https://entherium.duckdns.org:8443/mcp/readonly/ — тот же токен, только 7 читающих тулов (зачем)
Docs MCP, без токена	https://entherium.duckdns.org:8443/mcp/docs/ — эта документация как search / fetch / submit_feedback (подробнее)

Предусловия

• Есть агент-токен (<AGENT_TOKEN> ниже). Без него каждый вызов вернёт 401 — сначала запроси токен у владельца платформы.
• Твой HTTP-клиент умеет POST с кастомными заголовками и читает тело как текст. Ответы приходят как Server-Sent Events: бери строки, начинающиеся с data: , и парси остаток строки как JSON.

Шаг 1 — инициализируй сессию

curl -sS -D headers.txt https://entherium.duckdns.org:8443/mcp/ \
  -H "Authorization: Bearer <AGENT_TOKEN>" \
  -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. Скопируй его — это <SESSION_ID> для следующих шагов. Получил 401 — токен отсутствует или истёк, см. таблицу ниже. Не иди дальше, пока шаг не вернёт 200.

Шаг 2 — подтверди инициализацию

curl -sS https://entherium.duckdns.org:8443/mcp/ \
  -H "Authorization: Bearer <AGENT_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <SESSION_ID>" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

Ожидается: HTTP 2xx с пустым или тривиальным телом. Шаг обязателен — без него часть клиентов падает на последующих вызовах.

Шаг 3 — первый вызов тула

Всегда начинай с start_here: он возвращает упорядоченный план работы с платформой и capability-версию read-поверхности.

curl -sS https://entherium.duckdns.org:8443/mcp/ \
  -H "Authorization: Bearer <AGENT_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <SESSION_ID>" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"start_here","arguments":{}}}'

Ожидается: data:-строка с JSON плана. Дальше — по справочнику тулов: каждая страница тула показывает точный payload его tools/call.

Подключение из клиента одним шагом

Три curl-шага выше — то, что любой клиент делает под капотом. Клиенту достаточно URL и заголовка:

Claude Code

claude mcp add --transport http enterium https://entherium.duckdns.org:8443/mcp/readonly/ \
  --header "Authorization: Bearer <AGENT_TOKEN>"

Cursor / VS Code / любой клиент с mcp.json

{
  "mcpServers": {
    "enterium": {
      "url": "https://entherium.duckdns.org:8443/mcp/readonly/",
      "headers": { "Authorization": "Bearer <AGENT_TOKEN>" }
    }
  }
}

Замените readonly/ на /mcp/ только когда действительно нужны пишущие тулы. Для docs-сервера без токена ссылки установки работают как есть: Добавить в Cursor · Добавить в VS Code · 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; если поверхность изменилась, ответ перечислит, что принять к сведению до действий.