NotariumҚұжаттама
Құжаттама нұсқасы: latest
KZ

Агентті қосу

Агент Notarium-мен жалғыз эндпоинт — POST /mcp — арқылы сөйлеседі. Бұл — кірістірілген MCP шлюзі: веб-редактордағы қозғалтқыштың да, деректердің де дәл өзі, тек қоймаға тікелей қол жеткізудің орнына ниет құралдарының тар жиынтығы беріледі. Агентті екі жолмен қосуға болады: бағдарламалық клиенттерге жеке токенмен (PAT) немесе браузердегі claude.ai мен chatgpt.com үшін OAuth-коннектормен.

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

POST /mcp эндпоинты ресми @modelcontextprotocol/sdk кітапханасының streamable-HTTP транспортын іске асырады. Ол күйсіз (stateless): әр сұрауға сіздің токеніңіздің құқықтарымен жаңа сервер көтеріледі де, бір ғана JSON-жауап қайтады (SSE ағыны емес). GET пен DELETE әдістері 405 қайтарады — мұнда сервер бастамалайтын ағын жоқ.

Эндпоинт Claude API-дің MCP-коннекторымен, Claude Code-пен және Bearer-токен жібере алатын кез келген HTTP-MCP-клиентпен үйлесімді.

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-бөлігі жылдам іздеуге керек, ал құпия бөлігі дерекқорда тек хеш күйінде сақталып, шығарылған сәтте дәл бір рет қана көрсетіледі.

Токенді екі жолмен шығаруға болады:

  • Интерфейсте — баптаулардағы токендер бөлімі. Атауын, деңгейін (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 рөлін өзі атқарады — тапсыратын ешкім жоқ, тіркелгілерді өзіндік хостингтің өзі иеленеді).

Бұл былай жұмыс істейді:

  1. POST /mcp-ке токенсіз келген сұрау 401 қайтарады және WWW-Authenticate тақырыбымен discovery-құжаттарға (RFC 9728 / RFC 8414) сілтейді.
  2. Клиент GET /oauth/authorize арқылы өтеді — сіз ағымдағы сессияңызбен кіріп, consent-экранда кеңістіктерді таңдайсыз (бірнешеуін бірден, әдепкіде «All spaces»).
  3. PKCE (S256 әдісі) қолданатын POST /oauth/token 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 бәріне қолы жететін жалғыз субъект болады, ал claude.ai мен ChatGPT оны authless-коннектор ретінде ешқандай қосымша баптаусыз қосады. Бұл режимде OAuth-фасад жоқ.

Authless-сервер — ашық сервер

none режимінде URL-ді білген адам оны шақыра береді. Бұл тек бір пайдаланушылы (single-user) орнатуға, демоға немесе сенімді желіге ғана жарайды. Көппайдаланушылы дана үшін AUTH_MODE=password (әдепкі) қолданыңыз.

Әрі қарай