---
title: "Подключение агента"
description: "Как подключить ИИ-агента к Notarium: персональный токен (PAT), OAuth-коннектор для веб-клиентов и транспорт POST /mcp."
---

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

Агент общается с Notarium через один эндпоинт — `POST /mcp`. Это встроенный [MCP-гейтвей](/docs/agents/intent-tools/): тот же движок, те же данные, что и в веб-редакторе, но с узким набором интент-инструментов вместо прямого доступа к хранилищу. Подключить агента можно двумя способами: персональным токеном (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-токен.

```bash
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`, то есть выпуск токена доступен только вам самим через сессию, но не самому агенту (утёкший токен не выпустит новый).

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

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

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

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

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

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

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

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

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

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

## Дальше

- [Правила агента](/docs/agents/agent-files/) — как закрепить старт сессии со `start_session`, чтобы не напоминать вручную.
- [Интент-инструменты](/docs/agents/intent-tools/) — полный набор из 21 инструмента и порядок вызовов.
- [Безопасность и видимость](/docs/agents/security/) — как права применяются на каждом вызове.
- [Быстрый старт: подключить агента](/docs/getting-started/connect-agent/) — минимальный сквозной пример.