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

Агент общается с Notarium через один эндпоинт — POST /mcp. Это встроенный MCP-гейтвей: тот же движок, те же данные, что и в веб-редакторе, но с узким набором интент-инструментов вместо прямого доступа к хранилищу. Подключить агента можно двумя способами: персональным токеном (PAT) для программных клиентов или OAuth-коннектором для браузерных claude.ai и chatgpt.com.

Транспорт: POST /mcp

Эндпоинт POST /mcp реализует streamable-HTTP транспорт официального @modelcontextprotocol/sdk. Он stateless: на каждый запрос поднимается свежий сервер с правами вашего токена, и возвращается один JSON-ответ (не поток SSE). Методы GET и DELETE отдают 405 — серверных потоков здесь нет.

Эндпоинт совместим с MCP-коннектором Claude API, Claude Code и любым HTTP-MCP-клиентом, умеющим передавать Bearer-токен.

curl -sS https://notarium.example.com/mcp \
  -H "Authorization: Bearer ntp_<id>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Способ 1. Персональный токен (PAT)

PAT — основной способ для программных клиентов (Claude API, Claude Code, конфигурируемые MCP-клиенты). Токен передаётся в заголовке Authorization: Bearer <pat>.

Формат токена — ntp_<id>_<secret>: префикс ntp_ — чтобы токен было легко найти в логах и утечках, id-половина для быстрого поиска и секрет, который хранится в базе только как хеш и показывается ровно один раз при выпуске.

Выпустить токен можно двумя путями:

В UI — раздел токенов в настройках. Задаёте имя, уровень (read или write) и, при желании, сужение до конкретных пространств и срок действия.
По API — POST /api/me/tokens. Требует право self:manage, то есть выпуск токена доступен только вам самим через сессию, но не самому агенту (утёкший токен не выпустит новый).

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

read-токен даже не видит пишущие инструменты в tools/list — они не «появляются и отказывают», их просто нет в списке. Набор пространств токена определяет, куда агент дотянется; чужое пространство недостижимо в принципе. Права токена можно менять после выпуска (имя, уровень, набор пространств) без пересоздания секрета — изменение действует со следующего вызова.

Способ 2. OAuth-коннектор для веб-клиентов

Веб-интерфейсы claude.ai и chatgpt.com при добавлении «custom connector» принимают только OAuth — поля для вставки Bearer-токена там нет. Для этого Notarium несёт тонкий OAuth 2.1-фасад (Notarium выступает собственным Authorization Server — делегировать некуда, self-host владеет учётками).

Как это работает:

Запрос к POST /mcp без токена отдаёт 401 с заголовком WWW-Authenticate, указывающим на discovery-документы (RFC 9728 / RFC 8414).
Клиент проходит GET /oauth/authorize — вы логинитесь текущей сессией и на consent-экране выбираете пространства (мультивыбор, по умолчанию «All spaces»).
POST /oauth/token с PKCE (метод S256) выдаёт access-токен (nto_…) и, при offline_access, refresh-токен (ntr_…).

Выданный токен мапится на того же принципала и валидируется той же контрольной точкой, что PAT и сессия. Его уровень — read или write, но никогда manage: утёкший коннектор-токен не выпустит новый токен и не выдаст доступ. Управлять подключениями и менять их уровень или набор пространств можно в разделе Connected apps без повторного consent.

Claude и ChatGPT подключаются через OAuth

Notarium добавляется в ChatGPT как обычный коннектор поверх того же OAuth — так же, как в claude.ai: логин текущей сессией, выбор пространств на consent-экране, и агент видит ваш обычный набор интент-инструментов.

Режим none: без токена

Если инстанс запущен с AUTH_MODE=none (desktop, dev, доверенный интранет — оператор осознанно отключает аутентификацию), гейтвей работает без аутентификации: /mcp выступает единственным all-access принципалом, а claude.ai/ChatGPT добавляют его как authless-коннектор «из коробки». OAuth-фасада в этом режиме нет.

Authless-сервер публичен

В режиме none кто знает URL — тот вызывает. Это приемлемо только для single-user, демо или доверенной сети. Для мультипользовательского инстанса используйте AUTH_MODE=password (по умолчанию).

Дальше

Правила агента — как закрепить старт сессии со start_session, чтобы не напоминать вручную.
Интент-инструменты — полный набор из 21 инструмента и порядок вызовов.
Безопасность и видимость — как права применяются на каждом вызове.
Быстрый старт: подключить агента — минимальный сквозной пример.