Платформа NyxtaleИИ-помощник

Подключить ИИ (MCP)

Личный ключ, запуск сервера и конфиг клиента: агент работает с историями через тот же API, что и Studio.

Nyxtale отдаёт наружу тот же /v1, которым пользуется Studio, — а поверх него стоит MCP-сервер: мост, через который ИИ-клиент (Claude Code, Claude Desktop, Cursor, Gemini CLI) получает инструменты платформы как свои собственные. Агент читает и правит ваши истории, проверяет их, публикует — не кликая в интерфейсе и не выдумывая API.

Инструменты не написаны руками: они генерируются из OpenAPI-документа бэкенда при запуске сервера. Появился маршрут в API — появился инструмент, без второй правки и без расхождения между тем, что умеет платформа, и тем, что видит агент.

Три шага: взять ключ, запустить сервер, показать его клиенту.

Шаг 1. Личный ключ

Ключ выдаётся в Studio: профиль → раздел «Доступы». Кнопка создания просит подпись — это памятка себе («ноутбук», «рабочая машина»), на права она не влияет; пустую подпись заменит MCP.

Ключ показывается один раз. Он не хранится у нас в открытом виде и восстановить его нельзя: в списке потом остаются только первые символы (nyx_……), подпись и дата. Потеряли — выпустите новый, старый отзовите.

Что ключ означает:

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

Ключ — это доступ к вашему аккаунту. Не кладите его в общий репозиторий, в скриншот и в переписку.

Шаг 2. Сервер

На десктопе — одной кнопкой

В приложении Nyxtale в панели «Доступы» есть «Подключить». Она выпускает ключ и сохраняет его один раз централизованно — в ~/.nyxtale/mcp-token; сам ключ вам при этом не показывают, копировать нечего. Дальше при каждом сохранении проекта приложение кладёт в папку истории конфиги подключения — по одному на клиента:

Файл	Клиент
`.mcp.json`	Claude Code, Claude Desktop
`.cursor/mcp.json`	Cursor
`.gemini/settings.json`	Gemini CLI

Откройте ИИ-клиент в этой папке — инструменты Nyxtale подключатся сами. В самих конфигах ключа нет: сервер читает его из общего файла, поэтому папку можно передать или закоммитить, не раздав доступ к аккаунту.

Вручную

Сервер — один самодостаточный файл dist/nyxtale-mcp.mjs: обычный Node, без зависимостей и без экспериментальных флагов. Собирается из репозитория:

npm run build --workspace tools/nyxtale-mcp

Проверить, что он живой, можно прямо из терминала — при старте он пишет в stderr строку вида nyxtale-mcp: 94 operations [community] via dispatch … → https://api.nyxtale.com.

NYX_MCP_TOKEN=nyx_… node dist/nyxtale-mcp.mjs

Отдельного пакета в npm пока нет, поэтому конфига в одну строку через npx тоже пока нет: сервер берётся из сборки выше или из установленного десктопного приложения.

Шаг 3. Конфиг клиента

Все три клиента принимают одну и ту же форму записи — команда, аргументы, окружение. Для Claude Code и Claude Desktop это .mcp.json в папке проекта:

{
  "mcpServers": {
    "nyxtale": {
      "command": "node",
      "args": ["/absolute/path/to/nyxtale-mcp.mjs"],
      "env": { "NYX_MCP_TOKEN": "nyx_…" }
    }
  }
}

Для Cursor тот же объект кладётся в .cursor/mcp.json, для Gemini CLI — в .gemini/settings.json. Если ключ уже лежит в ~/.nyxtale/mcp-token (десктоп положил его туда сам), блок env не нужен вовсе — сервер найдёт токен сам.

Файл с ключом внутри — секрет. Добавьте его в .gitignore; десктопное приложение делает это за вас, дописывая недостающие строки к вашему существующему файлу, а не перезаписывая его.

Переменные окружения

Переменная	По умолчанию	Что делает
`NYX_MCP_TOKEN`	—	Ваш ключ из «Доступов». Пусто → сервер стартует, но каждый вызов упирается в 401
`NYX_MCP_TOKEN_FILE`	`~/.nyxtale/mcp-token`	Другое расположение файла с ключом
`NYX_MCP_API_BASE`	`https://api.nyxtale.com`	Адрес API. Меняют только для локальной разработки
`NYX_MCP_READONLY`	—	`1` — запретить всё, кроме чтения
`NYX_MCP_AUDIENCE`	`community`	Набор операций: `community` — публичные и авторские; `staff` — весь
`NYX_MCP_TOOLS`	`dispatch`	Как операции подаются помощнику: `dispatch` — три инструмента и поиск по каталогу; `flat` — по инструменту на каждую операцию

Почему помощник видит три инструмента, а не сотню

Операций в платформе под сотню, и если выдать их помощнику списком, он прочитает этот список целиком прежде, чем возьмётся за дело: примерно тридцать тысяч токенов вашего контекста, потраченных на оглавление. Со стороны это выглядит как долгая пауза «модель что-то обдумывает» перед первым действием.

Поэтому по умолчанию помощник получает три инструмента: nyx_operations — найти нужную операцию, nyx_describe — узнать её аргументы, nyx_call — вызвать. Каталог при этом никуда не делся: он ищется, а не читается наизусть. Ничего настраивать не нужно, это поведение по умолчанию; если ваш клиент почему-то не умеет так работать, верните старую выдачу через NYX_MCP_TOOLS=flat.

Как помощник правит историю: по одной сцене

Проект целиком — это сотни килобайт: у настоящей истории снимок весит около 380 КБ, и передать его аргументом инструмента, чтобы поправить одну строку, нельзя ни быстро, ни безопасно. Поэтому рукопись адресуется посценно, и агенту стоит сказать об этом прямо: «правь сцену, а не проект».

GET /v1/projects/{id}/scenes — оглавление: глава, id, имя, размер и отпечаток каждой сцены, без текста. Отсюда видно, что вообще есть и что изменилось;
GET /v1/projects/{id}/scenes/{scene} — текст одной сцены. Вместо {scene} годится и id, и имя, на которое прыгает -> имя;
PUT /v1/projects/{id}/scenes/{scene} — заменить одну сцену. Запись поверх непустого текста требует baseSha — тот отпечаток, который вернуло чтение. Проверка идёт по СЦЕНЕ, а не по проекту, поэтому двадцать правок подряд не начинают отказывать друг из-за друга;
POST /v1/projects/{id}/scenes — добавить сцену (по умолчанию в последнюю главу);
DELETE /v1/projects/{id}/scenes/{scene} — убрать сцену; отпечаток нужен так же, как при записи.

Что из этого следует помнить: написать сцену не значит связать её. Вход в новую сцену — это авторский переход -> имя в той сцене, откуда читатель должен туда попасть. После записи вызывайте POST /v1/projects/{id}/validate и смотрите connectivity.count — это число сцен, до которых читатель не доходит никак.

Каждая замена сцены сперва кладёт черновик в историю версий, так что стёртая страница возвращается восстановлением (GET /v1/projects/{id}/history → POST /v1/projects/{id}/restore).

Чего агент не сделает молча

Гарантии стоят на стороне сервера, а не на добросовестности модели:

необратимое требует подтверждения. Публикация, удаление проекта, возврат платежа и подобное не выполняются без явного "confirm": true в аргументах. В отказе перечислено, что именно и в каком объёме собирались тронуть, — подтверждаете вы не «операцию вообще», а конкретный список;
«всё» не является адресом. Селектор вида * или all, как и пустой список, отклоняется до отправки запроса: разрушительный вызов обязан назвать то, на что действует. Массовая операция ограничена 50 позициями за раз;
режим только чтения (NYX_MCP_READONLY=1) отменяет любую запись, даже корректно подтверждённую;
ключ не выходит наружу. Он передаётся только заголовком, не может быть аргументом инструмента и вычищается из всего, что возвращается модели, — включая ответ сервера, который попытался бы его отразить.

Если не подключается

Стартовая строка в stderr отвечает на большинство вопросов сразу — она называет число инструментов, профиль и адрес API.

[no token] в стартовой строке. Ключ не найден ни в NYX_MCP_TOKEN, ни в файле. Сервер при этом честно запускается, а каждый вызов возвращает 401.
mcp/http-error — HTTP 401. Ключ есть, но не принят: отозван, обрезан при копировании или это не тот ключ. Выпустите новый.
mcp/http-error — HTTP 403. Ключ ваш и действителен, но у аккаунта нет прав на это действие. Профиль инструментов — вещь грубая: community может показать агенту инструмент, который вашему конкретному аккаунту всё равно запрещён, и это выясняется на 403.
Агент не видит нужных инструментов. Проверьте профиль в стартовой строке: [community] — это публичная и авторская поверхность, служебные инструменты в ней отсутствуют намеренно.
mcp/confirmation-required. Не ошибка, а гейт: добавьте "confirm": true, прочитав, что перечислено в тексте отказа.
Клиент вообще не видит сервера. Конфиг читается из папки, в которой открыт клиент, — откройте его именно в папке истории. Путь в args должен быть абсолютным.
Ничего не отвечает, в логе мусор. Канал протокола — stdout; любая посторонняя печать туда ломает поток. Диагностика сервера пишется в stderr и на протокол не влияет.

MCP работает через stdio: клиент запускает процесс на вашей машине. Из браузера — только веб-Studio, без локального ИИ-приложения — подключиться нельзя.

Чего агент не видит: истории, которых нет в облаке

MCP ходит по HTTP, а HTTP знает только про облачные проекты. История, которая живёт лишь у вас — папка истории в настольном приложении или черновик в памяти браузерной Studio, — в списке GET /v1/projects не появится, и это не значит, что её нет. Из того же следует главное про удаление:

delete_v1_projects_by_id сносит облачную копию. Локальная — папка на диске, черновик в браузере — остаётся нетронутой;
на такую историю тот же инструмент ответит 404. Ответ один на две разные ситуации: проект уже удалён — или он никогда не уезжал в облако. Повторный вызов не поможет ни в одной;
локальную копию удаляют там, где она лежит: в Studio (она ведёт свой список удалённых, поэтому облачная досинхронизация её не воскресит) или, в настольном приложении, удалением папки истории.

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