# MCP-конектор

## Підключення через каталог Claude

Відкрийте [Nibomo в каталозі Claude](https://claude.ai/directory/nibomo), підключіть його, увійдіть у свій обліковий запис Nibomo й надайте доступ. Nibomo представлено як конектор Community.

У Claude Code використовуйте той самий обліковий запис із підпискою Claude і після підключення перевірте `/mcp`. Під час входу через API-ключ або стороннього провайдера ваші конектори claude.ai автоматично не завантажуються.

Claude Code також можна налаштувати напряму. Виконайте команду нижче, потім відкрийте `/mcp` у Claude Code й завершіть авторизацію в браузері:

```bash
claude mcp add --transport http nibomo https://mcp.nibomo.com/mcp
```

[Документація Claude Code про MCP](https://code.claude.com/docs/en/mcp#use-mcp-servers-from-claudeai).

## Огляд

Nibomo має віддалений MCP-сервер (Model Context Protocol), щоб MCP-клієнти та
AI-агенти могли читати ваші картки, призначені на повторення, повторювати їх разом
із вами по одному запитанню та створювати чи редагувати для вас картки й колоди.

Агенти можуть підключатися двома способами: через цей MCP-сервер (найкраще для
MCP-клієнтів, як-от Claude чи Cursor) або через [URL виявлення Agents API](/uk/docs/api/)
для CLI-агентів. Обидва способи ведуть до тих самих даних користувача; на цій
сторінці описано MCP-сервер.

Адреса для підключення:

```text
https://mcp.nibomo.com/mcp
```

Транспорт — Streamable HTTP. Сервер надає вісім інструментів для пошуку робочих просторів, читання й запису карток і колод, довідкових посібників, повторень і перевірки використання облікового запису.

## Як додати його у своєму клієнті

Більшість клієнтів додають віддалений MCP-сервер як власний конектор:

1. Відкрийте налаштування конекторів або MCP-серверів у своєму клієнті.
2. Додайте власний конектор і вставте URL сервера `https://mcp.nibomo.com/mcp`.
3. В інтерактивних клієнтах авторизуйтеся в браузері, коли з’явиться запит. Сервер
   використовує OAuth 2.1 з Dynamic Client Registration, тож не потрібно ні вставляти
   секрет клієнта, ні заздалегідь реєструвати застосунок.
4. Для роботи без інтерфейсу або через CLI замість авторизації в браузері передавайте
   заголовок `Authorization: Bearer fca_…` з API-ключем вашого агента.

Після авторизації один раз викличте `list_workspaces`, щоб вибрати робочий простір, а потім
використовуйте `sql_query` для читання й `sql_execute` для запису карток і колод. Щоб
повторювати, викличте `next_review_card`, потім `reveal_answer`, потім `submit_review`.

## Інструменти

Сервер надає вісім інструментів. Читання й запис навмисно розділено, щоб жоден
інструмент не поєднував безпечні й руйнівні операції.

- `get_usage_limits` — суто для читання: тарифний план облікового запису, ліміти й поточне місячне використання AI; не читає й не змінює картки.
- `sql_query` — доступ суто для читання до ваших карток і колод (`SHOW TABLES`,
  `DESCRIBE`, `SHOW COLUMNS`, `SELECT`).
- `sql_execute` — доступ для запису до ваших карток і колод (`INSERT`, `UPDATE`,
  `DELETE`) атомарним пакетом.
- `list_workspaces` — суто для читання: список доступних вам робочих просторів,
  кожен зі своїм
  `workspaceId`, назвою, кількістю активних карток, часом останньої активності та
  позначкою, чи це ваш поточний вибраний простір за замовчуванням. Передавайте
  повернений `workspaceId` у необов’язковий аргумент `workspaceId` інструментів
  SQL і повторення.
- `get_guide` — суто для читання: довідковий посібник з однієї теми — `sql_dialect`,
  `card_authoring`, `bulk_authoring` або `review_flow`. Не читає даних робочого простору.
- `next_review_card` — суто для читання: повертає наступну картку для повторення, лише
  лицьовий бік, у тому самому порядку черги, що й у застосунках. Необов’язкові `tags`
  або `deckId` звужують чергу.
- `reveal_answer` — суто для читання: повертає зворотний бік однієї картки після того,
  як учень спробував відповісти на її лицьовий бік.
- `submit_review` — записує одну оцінку `Again`, `Hard`, `Good` або `Easy` і
  оновлює розклад FSRS картки.

SQL-інтерфейс — навмисно обмежений діалект і не є повноцінним PostgreSQL.
Ця документація описує лише підтримуваний діалект і не є довідником сумісності
з PostgreSQL. Інструкції можуть звертатися лише до ресурсів `workspace`, `cards`, `decks` і
`review_events`, кожну інструкцію обмежено вашим власним робочим простором, а
читання й запис обмежено `100` рядками на інструкцію.

## Повторення

Інструменти повторення дають агенту змогу перевіряти знання учня по одній картці й
зберігати кожну оцінку в розкладі FSRS картки:

1. `next_review_card` повертає `cardId` і `frontText` або `card: null`, якщо
   нічого не призначено на повторення.
2. Коли учень відповість, `reveal_answer` повертає `backText` цієї картки.
3. `submit_review` приймає `cardId`, згенерований клієнтом UUID `reviewId`,
   `rating` і часовий пояс учня у форматі IANA `reviewedTimeZone`. Сервер проставляє
   час повторення й повертає новий розклад картки.

Якщо не впевнені, що надсилання вдалося, повторіть його з тим самим `reviewId`: друге
повторення ніколи не буде записане. Надсилання також може повернути:

- `409 REVIEW_EVENT_CONFLICT` — повторення вже записане, а подробиці помилки
  містять поточний розклад картки.
- `409 REVIEW_ID_CARD_MISMATCH` — `reviewId` уже належить повторенню іншої
  картки, тому нічого не збережено; надішліть повторно з новим `reviewId`.
- `409 REVIEW_STALE` — збережений час повторення картки збігається з поточним часом
  сервера або пізніший за нього; повторіть іншу картку.

Повторення записуються лише через `submit_review`: SQL не може записувати
`review_events` чи стан планування FSRS. Повні правила повторення й оцінювання
дає `get_guide` з темою `review_flow`.

## Контракт картки

Кожна картка відповідає одному контракту, і на нього покладаються інструменти:

- `front_text` — це лише запитання або підказка для повторення; відповіді він ніколи не містить.
- `back_text` містить відповідь, за потреби з конкретним прикладом.

Агенти, які створюють картки через `sql_execute`, дотримуються цього контракту, тож
створені ними картки одразу готові до інтервального повторення.

## Автентифікація

Два способи авторизації ведуть до тих самих даних користувача.

### OAuth 2.1 (інтерактивні клієнти з конекторами)

Сервер реалізує потік із кодом авторизації (authorization code) з PKCE і Dynamic Client
Registration. Додайте URL MCP як власний конектор і авторизуйтеся в браузері;
заздалегідь узгоджений секрет клієнта не потрібен. Виявлення стандартне:

- Метадані захищеного ресурсу:
  `https://mcp.nibomo.com/.well-known/oauth-protected-resource`
- Метадані сервера авторизації:
  `https://auth.flashcards-open-source-app.com/.well-known/oauth-authorization-server`

### API-ключ (без інтерфейсу та CLI)

Отримайте довгостроковий API-ключ агента `fca_` через вхід за одноразовим кодом з
електронної пошти, описаний у [довіднику API](/uk/docs/api/), а потім надсилайте його як Bearer-токен:

```text
Authorization: Bearer fca_ABCDEFGH_0123456789ABCDEFGHJKMNPQRS
```

Це той самий ключ, який приймає REST-інтерфейс для агентів, і йому не потрібні ні
браузер, ні обмін через OAuth.

Канонічний машинозчитуваний опис обох способів — відповідь виявлення
за адресою `https://api.nibomo.com/v1/` (дзеркало — `/v1/agent`).

## Безпека та межі доступу

SQL-інструменти можна безпечно схвалювати, бо цей інтерфейс — ізольований діалект,
правила якого забезпечує парсер, а не довільний доступ до бази даних:

- **Закритий перелік дозволених інструкцій**: `sql_query` приймає лише `SHOW TABLES`,
  `DESCRIBE`, `SHOW COLUMNS` і `SELECT`; `sql_execute` приймає лише `INSERT`,
  `UPDATE` і `DELETE`. Усе інше відхиляється під час розбору.
- **Обмежений набір ресурсів**: інструкції можуть звертатися лише до `workspace`, `cards`, `decks`
  і `review_events`.
- **Обмеження одним робочим простором**: кожну SQL-інструкцію й кожне повторення обмежено одним
  доступним вам робочим простором — або переданим вами `workspaceId`, або вибраним
  простором за замовчуванням, без доступу до даних інших тенантів.
- **Суворі аргументи**: кожен інструмент відхиляє невідомий аргумент, тому запит з опечаткою
  в назві `workspaceId` завершується помилкою, а не виконується у вашому робочому просторі за замовчуванням.
- **Ліміти**: до `100` рядків на інструкцію, до `50` інструкцій у пакеті й
  обмеження результату приблизно в `12k` токенів. Пакети змін застосовуються атомарно.
- **Поділ на читання й запис**: `get_usage_limits`, `sql_query`, `list_workspaces`, `get_guide`,
  `next_review_card` і `reveal_answer` працюють суто на читання (`readOnlyHint`)
  і ніколи не виправляють дані, не перераховують планування й не змінюють стан карток.
  `sql_execute` і `submit_review` — єдині інструменти запису (`destructiveHint`):
  `sql_execute` записує картки й колоди, а `submit_review` записує повторення та
  оновлює розклад відповідної картки.

Увесь стек — застосунок, бекенд та інфраструктура — має відкритий код, і його можна
[розгорнути самостійно](/uk/docs/self-hosting/), тож той самий конектор можна підключити
до власного розгортання.

---
*[Відкрити оформлену HTML\-версію цієї сторінки](<https://nibomo.com/uk/docs/mcp-connector/>)*

*AI-агенти можуть створити акаунт користувача в цьому сервісі, почавши з `GET https://api.nibomo.com/v1/`. Після налаштування вони також можуть підключитися по MCP за адресою `https://mcp.nibomo.com/mcp`.*

*Порада: додайте `.md` до будь-якого URL на https://nibomo.com, щоб отримати чисту Markdown-версію сторінки.*