# MCP-коннектор

## Обзор

Flashcards предоставляет удалённый MCP-сервер (Model Context Protocol), чтобы
MCP-клиенты и агенты ИИ могли читать ваши карточки к повторению, а также создавать
и редактировать карточки и колоды за вас.

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

Подключайтесь по адресу:

```text
https://mcp.flashcards-open-source-app.com/mcp
```

Транспорт — Streamable HTTP, и сервер предоставляет три инструмента поверх
небольшого, намеренно ограниченного SQL-интерфейса. Это тот же набор данных на
уровне пользователя, что и в [справочнике API](/ru/docs/api/); MCP-сервер — это удобный
для коннекторов способ получить к нему доступ из клиентов, которые поддерживают MCP.

## Как добавить его в вашем клиенте

Большинство клиентов добавляют удалённый MCP-сервер как пользовательский коннектор:

1. Откройте в вашем клиенте настройки коннекторов или MCP-серверов.
2. Добавьте пользовательский коннектор и вставьте URL сервера `https://mcp.flashcards-open-source-app.com/mcp`.
3. Для интерактивных клиентов авторизуйтесь в браузере, когда появится запрос. Сервер
   использует OAuth 2.1 с Dynamic Client Registration, поэтому нет client secret,
   который нужно было бы вставлять, и нет приложения, которое нужно регистрировать заранее.
4. Для headless- или CLI-использования вместо браузерного потока задайте заголовок
   `Authorization: Bearer fca_…` с вашим API-ключом агента.

После авторизации один раз вызовите `list_workspaces`, чтобы выбрать workspace, а
затем используйте `sql_query` для чтения и `sql_execute` для записи.

## Инструменты

Сервер предоставляет три инструмента. Чтение и запись разделены намеренно, чтобы один
инструмент никогда не смешивал безопасные и разрушительные операции.

- `sql_query` — доступ только для чтения к вашим карточкам и колодам (`SHOW TABLES`,
  `DESCRIBE`, `SHOW COLUMNS`, `SELECT`).
- `sql_execute` — доступ на запись к вашим карточкам и колодам (`INSERT`, `UPDATE`,
  `DELETE`) в виде атомарного пакета.
- `list_workspaces` — список доступных вам workspace, для каждого с его `workspaceId`,
  именем, числом активных карточек, временем последней активности и признаком того,
  является ли он вашим текущим выбранным workspace по умолчанию. Используйте
  возвращённый `workspaceId` в качестве аргумента `workspaceId` для `sql_query` и `sql_execute`.

SQL-интерфейс — это намеренно ограниченный диалект, а не полноценный PostgreSQL.
Выражения могут обращаться только к ресурсам `workspace`, `cards`, `decks` и
`review_events`, каждое выражение ограничено вашим собственным workspace, а чтение и
запись ограничены `100` строками на выражение.

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

Каждая карточка следует одному контракту, и инструменты опираются на него:

- `front_text` — это только вопрос или подсказка к повторению и никогда не содержит ответа.
- `back_text` содержит ответ, при необходимости с конкретным примером.

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

## Аутентификация

Два пути авторизации ведут к одному и тому же набору данных на уровне пользователя.

### OAuth 2.1 (интерактивные клиенты-коннекторы)

Сервер реализует поток authorization-code с PKCE и Dynamic Client Registration.
Добавьте URL MCP как пользовательский коннектор и авторизуйтесь в браузере; client
secret заранее не передаётся. Discovery выполняется стандартно:

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

### API-ключ (headless и CLI)

Получите долгоживущий API-ключ агента `fca_` через поток входа по одноразовому коду
из письма, описанный в [справочнике API](/ru/docs/api/), а затем отправляйте его как Bearer-токен:

```text
Authorization: Bearer fca_ABCDEFGH_0123456789ABCDEFGHJKMNPQRS
```

Это тот же ключ, который принимает REST-интерфейс для агентов, и ему не нужны ни
браузер, ни round-trip через OAuth.

Каноническое машиночитаемое описание обоих путей — это полезная нагрузка discovery
по адресу `https://api.flashcards-open-source-app.com/v1/` (с зеркалом на `/v1/agent`).

## Безопасность и область действия

SQL-инструменты безопасно одобрять, потому что этот интерфейс — изолированный диалект
с проверкой на уровне парсера, а не произвольный доступ к базе данных:

- **Закрытый список разрешённых выражений**: `sql_query` принимает только `SHOW TABLES`,
  `DESCRIBE`, `SHOW COLUMNS` и `SELECT`; `sql_execute` принимает только `INSERT`,
  `UPDATE` и `DELETE`. Всё остальное отклоняется на этапе разбора.
- **Ограниченные ресурсы**: выражения могут обращаться только к `workspace`, `cards`,
  `decks` и `review_events`.
- **Ограничение по workspace**: каждое выражение ограничено выбранным вами workspace,
  без доступа к данным других арендаторов.
- **Лимиты**: до `100` строк на выражение, до `50` выражений в пакете и ограничение
  результата примерно в `12k` токенов. Пакеты изменений применяются атомарно.
- **Разделение чтения и записи**: `sql_query` и `list_workspaces` работают только на
  чтение (`readOnlyHint`), а `sql_execute` выполняет запись (`destructiveHint`).

Весь стек — приложение, бэкенд и инфраструктура — имеет открытый исходный код и может
быть [развёрнут самостоятельно](/ru/docs/self-hosting/), так что вы можете запустить тот
же коннектор против собственного развёртывания.

---
*[Открыть оформленную HTML-версию этой страницы](https://flashcards-open-source-app.com/ru/docs/mcp-connector/)*

*AI-агенты могут создать аккаунт пользователя в этом сервисе, начиная с `GET https://api.flashcards-open-source-app.com/v1/`. После настройки они также могут подключиться по MCP по адресу `https://mcp.flashcards-open-source-app.com/mcp`.*

*Совет: добавьте `.md` к любому URL на https://flashcards-open-source-app.com, чтобы получить чистую Markdown-версию страницы.*