MCP

Те саме API, адресоване асистентові, а не сценарію. MCP-клієнт вибирає, що викликати, під час роботи — з описів інструментів, — тож дістає він рівно те, що дістають його облікові дані, і під кожним інструментом лежить виклик публічного API.

Одна адреса

Усе йде на POST /v1/mcp. Сесії відкривати нема чого, потік тримати теж: GET і DELETE відповідають 405, і кожне повідомлення — окремий запит.

POST https://api.mosaqo.app/v1/mcp
Authorization: Bearer $MOSAQO_KEY
MCP-Protocol-Version: 2026-07-28

Ревізії протоколу від 2025-03-26 до 2026-07-28 обслуговуються всі. Клієнт, який відкриває initialize, отримує хендшейк, на який розраховує; той, що називає версію в кожному запиті, — обслуговується так.

Підключення ключем API

Найшвидший шлях і правильний для інструмента, який ви тримаєте самі. Будь-який ключ працює як bearer-токен, а набір інструментів обрізається до скоупів цього ключа.

Більшість клієнтів приймає такий блок:

{
  "mcpServers": {
    "mosaqo": {
      "type": "http",
      "url": "https://api.mosaqo.app/v1/mcp",
      "headers": { "Authorization": "Bearer $MOSAQO_KEY" }
    }
  }
}

curl -X POST https://api.mosaqo.app/v1/mcp \
  -H "Authorization: Bearer $MOSAQO_KEY" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/list" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'

Підключення через OAuth

Для конектора в чужому каталозі, де людина ключа взагалі не торкається. Виявлення за RFC 9728 і RFC 8414, клієнти реєструються самі за RFC 7591, кожна авторизація — PKCE з S256.

curl https://api.mosaqo.app/.well-known/oauth-protected-resource
curl https://api.mosaqo.app/.well-known/oauth-authorization-server

Неавторизований виклик сам каже, куди йти і що просити:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="Mosaqo MCP",
  resource_metadata="https://api.mosaqo.app/.well-known/oauth-protected-resource",
  scope="qr:read analytics:read reviews:read exports:read"

Той, хто підтверджує, увійшов у Mosaqo, обирає, якого простору це стосується, і може це зробити лише там, де він власник або адміністратор — та сама межа, що вирішує, хто видає ключ API. Відключити можна потім у Bulk & API.

Що асистент може

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

Скоуп	Дає право
`qr:read`	Читати список і вміст QR-кодів, папки та шаблони
`qr:write`	Створювати, змінювати, перецілювати, публікувати, архівувати й видаляти
`exports:read`	Завантажувати відрендерені картки
`analytics:read`	Зведену аналітику та окремі сканування
`bulk:write`	Створювати й читати пакетні завдання
`webhooks:write`	Керувати підписками на webhooks
`reviews:read`	Місця, опитування й те, як вони йдуть — але не самі відповіді

Чого він не дістане ніколи

Того, що люди написали в опитуванні. reviews:read відкриває ваші місця, опитування й те, як вони йдуть, — кількості, оцінки, розподіл відповідей по кожному питанню. Речення, які набрав відвідувач, тут віддаються не більше, ніж будь-де ще, куди дістають облікові дані, — з тієї самої причини, з якої події feedback.* несуть оцінку й ніколи слова.

Видалення коду. REST-маршрут вимагає набраного підтвердження, бо знищення редиректу за надрукованим кодом незворотне, а таке підтвердження асистент за людину не дає. Натомість є архівація, і вона зворотна.

Запис позначений як запис. Інструмент, що змінює щось, несе readOnlyHint: false, а архівація — destructiveHint: true: саме через це клієнт зупиняється й питає людину перед запуском.