---
title: "Агентті қосу"
description: "Notarium-ге ЖИ-агентті қалай қосуға болады: жеке токен (PAT), веб-клиенттерге арналған OAuth-коннектор және POST /mcp транспорты."
---

# Агентті қосу

Агент Notarium-мен жалғыз эндпоинт — `POST /mcp` — арқылы сөйлеседі. Бұл — кірістірілген [MCP шлюзі](/docs/agents/intent-tools/): веб-редактордағы қозғалтқыштың да, деректердің де дәл өзі, тек қоймаға тікелей қол жеткізудің орнына ниет құралдарының тар жиынтығы беріледі. Агентті екі жолмен қосуға болады: бағдарламалық клиенттерге жеке токенмен (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-клиентпен үйлесімді.

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

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

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

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

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 сұрамай-ақ болады.

> [!note] Claude мен ChatGPT OAuth арқылы қосылады
> Notarium ChatGPT-ге дәл сол OAuth үстіндегі кәдімгі коннектор ретінде қосылады — claude.ai-дегі сияқты: ағымдағы сессиямен кіресіз, consent-экранда кеңістіктерді таңдайсыз, әрі агент сіздің әдеттегі ниет құралдарының жиынтығын көреді.

## none режимі: токенсіз

Дана `AUTH_MODE=none`-мен іске қосылса (desktop, dev, сенімді интранет — оператор аутентификацияны әдейі өшіреді), шлюз аутентификациясыз жұмыс істейді: `/mcp` бәріне қолы жететін жалғыз субъект болады, ал 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/) — минималды ұштан-ұшқа мысал.