NotariumДокументация
Версия документации: latest
RU

Подключить агента

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

Эта страница — быстрый путь: выпустить токен, указать эндпоинт и убедиться, что агент видит базу. Полный контракт (инструменты, конвенции вызовов, память, аудит, безопасность) — в разделе Агенты и MCP.

Шаг 1. Выпустить токен

Агент аутентифицируется персональным токеном доступа (PAT). Выпустите его в настройках своего аккаунта (раздел токенов) — там же задаётся:

  • scope — read или write (потолок прав токена);
  • опциональное сужение по пространствам — какие пространства достижимы;
  • опциональный срок жизни.

Токен имеет вид ntp_<id>_<secret> и показывается ровно один раз — скопируйте его сразу. Утёкший PAT не эскалируется: управляющие действия (выпуск токенов, членство, создание пространств) доступны только под сессией человека, не по токену.

Права токена — это потолок агента

Read-only токен физически не видит пишущих инструментов: они не появляются в его наборе. Чужое пространство недостижимо в принципе. Выдавайте агенту ровно те права, что нужны задаче.

Шаг 2. Указать эндпоинт

Настройте агента (или MCP-клиент) на эндпоинт:

POST http://localhost:3000/mcp
Authorization: Bearer ntp_<id>_<secret>

Транспорт — streamable-HTTP официального MCP-SDK, stateless, один JSON-ответ на запрос (GET/DELETE отвечают 405). Эндпоинт совместим с MCP-коннектором Claude API и любым HTTP-MCP-клиентом.

Веб-коннекторы claude.ai и chatgpt.com

В custom-коннекторы веб-интерфейсов PAT вставить нельзя — они работают только через OAuth. Notarium несёт тонкий OAuth-фасад: коннектор проходит вход вашей сессией и получает токен, сопоставляемый тому же принципалу. Детали — в разделе Подключение агента.

Шаг 3. Первый вызов — start_session

В новой сессии агент вызывает start_session первым. За один запрос он получает профиль, список доступных проектов и дельту изменений с прошлого визита, а если передать подсказку project — ещё и компактный индекс этого проекта. Это контекст, с которого стоит начинать работу.

Дальше — привычный порядок: осмотреть структуру (list_notes, recent_activity), поискать перед записью (search — дедуп), затем писать (create_note, edit_note, память remember_about_user / remember_about_project). Агент работает через узкий набор инструментов под конкретные задачи, а не через универсальные операции чтения/записи — каждый инструмент навязывает безопасное поведение (класс заметки, видимость, провенанс, проверка версии при сохранении, чтобы не затереть чужие правки).

Не выставляйте none-инстанс в сеть

В режиме AUTH_MODE=none эндпоинт /mcp открыт без токена (единственный all-access принципал). Это удобно для рабочего стола и доверенного окружения, но такой инстанс нельзя открывать в публичную сеть.

Шаг 4. Закрепить это в правилах агента

Какой инструмент вызвать — решает модель, поэтому «звать start_session первым» стоит записать один раз в постоянную инструкцию агента (CLAUDE.md, AGENTS.md, правила Cursor, системный промпт) — вместе с хэндлом вашего проекта:

- В начале новой сессии вызови `start_session(project: "acme/website")`
  на MCP-сервере `notarium`.
- Перед любой записью сначала `search(...)` — не плоди дубли.

Без этого агенту приходится напоминать про базу знаний каждый раз вручную. Развёрнуто, с картой канона и разделением глобальных и проектных правил, — Правила агента.

Дальше