Сервер MCP для Ментор

Що це і кому потрібне

MCP (Model Context Protocol) — відкритий протокол, яким ШІ-застосунки звертаються до зовнішніх інструментів. Сервер Ментор показує агентові набір інструментів із префіксом tutor_: створити урок, додати чи змінити блок, скласти курс, запустити генерацію, опублікувати.

• Вам потрібні готові матеріали в Ментор, а писати вправи вручну довго: опишіть агентові урок — він створить його одним викликом.
• Ви вже користуєтеся Claude, Cursor чи іншим клієнтом MCP і хочете працювати з уроками звідти.
• Ви автоматизуєте виробництво матеріалів власним скриптом: протокол відкритий, а кожен інструмент описано з прикладами.

Агент працює від вашого імені й лише в межах дозволів токена. Створене ним — чернетки, які бачите тільки ви.

Підключення

1. Відкрийте в Ментор сторінку «Налаштування» і знайдіть картку «Доступ для ШІ-агентів».
2. Натисніть «Створити токен», дайте йому назву (наприклад, «Claude на ноутбуці»), оберіть дозволи й термін дії.
3. Скопіюйте токен одразу: повністю він показується лише один раз. Далі в списку видно лише назву та останні символи.
4. Вставте токен у налаштування вашого клієнта за одним із прикладів нижче.

Адреса сервера — https://mentor.chitay.org.ua/api/mcp. Сервер працює за протоколом MCP (Streamable HTTP) і приймає лише запити POST із заголовком Authorization: Bearer <токен>.

Claude Code. Виконайте команду в терміналі.

claude mcp add --transport http chitay https://mentor.chitay.org.ua/api/mcp --header "Authorization: Bearer chitay_pat_ВАШ_ТОКЕН"

Codex. Токен Codex читає зі змінної середовища, а не з файлу. Виконайте в терміналі:

export CHITAY_MCP_TOKEN="chitay_pat_ВАШ_ТОКЕН"
codex mcp add chitay --url https://mentor.chitay.org.ua/api/mcp --bearer-token-env-var CHITAY_MCP_TOKEN

Cursor. Додайте запис до ~/.cursor/mcp.json (або .cursor/mcp.json у проєкті).

{
  "mcpServers": {
    "chitay": {
      "url": "https://mentor.chitay.org.ua/api/mcp",
      "headers": {
        "Authorization": "Bearer chitay_pat_ВАШ_ТОКЕН"
      }
    }
  }
}

VS Code. Додайте до .vscode/mcp.json. Не зберігайте цей файл у git разом із токеном.

{
  "servers": {
    "chitay": {
      "type": "http",
      "url": "https://mentor.chitay.org.ua/api/mcp",
      "headers": {
        "Authorization": "Bearer chitay_pat_ВАШ_ТОКЕН"
      }
    }
  }
}

Gemini CLI. Виконайте команду в терміналі.

gemini mcp add --transport http -H "Authorization: Bearer chitay_pat_ВАШ_ТОКЕН" chitay https://mentor.chitay.org.ua/api/mcp

Claude Desktop. Файл налаштувань Claude Desktop не приймає віддалені адреси напряму, тож підключення йде через міст mcp-remote (потрібен Node.js). Додайте запис до claude_desktop_config.json.

{
  "mcpServers": {
    "chitay": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mentor.chitay.org.ua/api/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer chitay_pat_ВАШ_ТОКЕН"
      }
    }
  }
}

Інший клієнт (HTTP). Будь-який клієнт MCP із підтримкою Streamable HTTP. Перевірка з терміналу:

curl -X POST https://mentor.chitay.org.ua/api/mcp \
  -H "Authorization: Bearer chitay_pat_ВАШ_ТОКЕН" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Токен — це пароль до вашого облікового запису в межах обраних дозволів. Не передавайте його іншим і не публікуйте. Якщо токен потрапив не до тих рук, відкличте його в налаштуваннях: він перестане діяти одразу.

Дозволи, ліміти й чернетки

Кожен токен має один або кілька дозволів. Кожен інструмент вимагає одного з них; у довіднику він указаний біля назви.

Усе, що агент створює, — приватні чернетки. Жоден інструмент не видає урок учням і не надсилає повідомлень: викладач відкриває посилання reviewUrl, переглядає результат і вирішує сам.

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

Курс має спосіб проходження pacing: teacher_paced — уроки відкриває викладач (типово), self_paced — учень сам завершує урок і відкриває наступний. Щойно на курс когось записано, змінити спосіб уже не можна: tutor_update_course відповідає кодом conflict.

Ще два поля курсу — списки forWhom («Для кого цей курс») і outcomes («Що ви отримаєте після курсу»). Їх бачать студенти курсу, а після публікації — відвідувачі сторінки курсу на Читай. До 8 пунктів, кожен до 200 видимих символів; з форматування лишаються тільки **жирний**, *курсив* і ~~закреслений~~, решта прибирається. Список замінюється цілком; null або [] очищає його. tutor_get_course повертає обидва списки.

Щоб перевірити токен, достатньо викликати tools/list. Список інструментів повертається для будь-якого дозволу — агент бачить усе, що існує, навіть якщо викладач ще не дав права цим скористатися.

Форматований текст

Опис курсу, пункти forWhom / outcomes, опис уроку і правило в блоці theory — форматований текст: невелика частина markdown. Його зберігають і повертають (tutor_get_course, tutor_get_lesson) таким, як написано, а студентам показують відформатованим.

• Видимі символи — те, що бачить читач: маркери, - / 1. / > на початку рядка, зворотні скісні й наголос не рахуються, перенос рядка — один символ.
• Більше за ліміт — validation_failed зі шляхом до поля (description, lesson.description, forWhom[2]).
• Розмітка, якої поле не має, не помилка: її зберігають, як написано, і показують звичайним текстом. Порожні пари маркерів прибираються.

Формат помилок

Якщо інструмент не виконався, відповідь має ознаку isError: true і один текстовий елемент із JSON такого вигляду:

{
  "error": {
    "code": "validation_failed",
    "message": "Вхідні дані не прийнято: 2 проблеми.",
    "problems": [
      {
        "path": "lesson.worksheets[0].blocks[3].content.questions[1].options",
        "code": "schema",
        "message": "Має бути щонайменше 2 варіанти відповіді."
      },
      {
        "path": "lesson.worksheets[0].blocks[3].content[q2]",
        "code": "invariant",
        "message": "Ключ посилається на варіант, якого немає."
      }
    ]
  }
}

• code стабільний: за ним агент вирішує, що робити. Перелік кодів — у довіднику.
• message написано для людини, його формулювання може змінитися. Повідомлення перевірки блоків українською, як і для викладачів у веб-інтерфейсі.
• problems є лише в validation_failed і містить усі знайдені проблеми одразу, тож виправити можна за одну спробу.
• path — шлях до місця помилки від кореня аргументів виклику: a.b[0].c. Елемент списку блока, у якого є id, позначено ним у квадратних дужках.
• Поле, якого інструмент не знає, теж validation_failed зі шляхом до цього поля — його ніколи не відкидають мовчки.

Помилки автентифікації — це HTTP-відповіді до початку роботи з MCP: 401 (токен відсутній, невідомий, відкликаний або прострочений; заголовок WWW-Authenticate: Bearer realm="chitay-mcp", resource_metadata="…" — за ним OAuth-клієнт знаходить, де увійти) і 403, якщо обліковий запис уже не має доступу.

Що зберігається

Токен зберігається лише у вигляді одностороннього відбитка: відновити його з бази неможливо. Для кожного виклику записується журнал — хто (токен), який інструмент, з яким результатом, коли й скільки тривало. Вмісту уроків, учнів і IP-адрес у журналі немає; записи видаляються через 90 днів.

Версії

Сервер повідомляє версію в serverInfo.version і дотримується семантичного версіювання. Мажорна версія змінюється, якщо інструмент або поле зникає, перейменовується чи змінює значення; додавання інструмента або необов’язкового поля — мінорна; виправлення опису чи документації — патч. Кожна зміна записується в журналі змін. Попередні випуски (-beta.N) можуть змінювати що завгодно, і це буде сказано в журналі.