Сервер MCP
API B1 містить сервер MCP (Model Context Protocol) за адресою /mcp. До нього може під'єднатися будь-який ШІ-клієнт із підтримкою MCP: користувацькі коннектори claude.ai, Claude Code, Claude Desktop, OpenAI Agents SDK, Cursor або ваш власний застосунок. Такий клієнт може викликати базовий REST API від імені автентифікованого користувача церкви. Це тонка універсальна обгортка: три загальні інструменти динамічно відкривають весь API, замість того щоб вручну описувати кожен ендпоїнт, а ще один інструмент надає довідку для конструктора веб-сайтів.
Перш ніж почати
- Ключ API B1 (
cak_…) з областями доступу, які потрібні клієнту, або MCP-клієнт, який може входити через OAuth (див. Виявлення OAuth) - Доступний хост API B1:
https://api.churchapps.orgдля розміщених церков або ваше власне розгортання - Клієнт MCP. Інструкції з налаштування для кінцевих користувачів див. у розділах Claude і ChatGPT
Ендпоїнт
POST /mcp
Content-Type: application/json
Accept: application/json, text/event-stream
Authorization: Bearer cak_<prefix>.<secret>
| Аспект | Значення |
|---|---|
| Шлях | /mcp (відносно хоста API) |
| Метод | лише POST. І запити з відповідями, і потокова передача SSE відбуваються на одному ендпоїнті |
| Транспорт | MCP Streamable HTTP |
| Модель сесій | Без збереження стану. Для кожного запиту створюється новий екземпляр сервера MCP, без ідентифікатора сесії та без відновлення |
| Автентифікація | Bearer-токен. Працюють ключі cak_… і JWT B1 (зокрема токени доступу OAuth). Розпізнавання таке саме, як для будь-якого іншого автентифікованого ендпоїнта |
Запит, у якого заголовок Authorization відсутній або недійсний, повертає:
{ "error": "Unauthorized — MCP requires a valid bearer token (cak_* API key or JWT)." }
з HTTP-статусом 401 і заголовком WWW-Authenticate: Bearer resource_metadata="<api>/.well-known/oauth-protected-resource". OAuth-клієнти використовують цей заголовок, щоб почати вхід.
У розміщеному API (продакшн і демо) /mcp обслуговується через HTTP API шлюзу API Gateway, а не через REST API, який використовується для решти ендпоїнтів. REST API перейменовує WWW-Authenticate на x-amzn-remapped-www-authenticate у відповідях проксі Lambda. Через це такі клієнти, як ChatGPT, отримували голу відповідь 401 без можливості почати вхід. HTTP API передає заголовок без змін.
Інструменти
Три загальні інструменти та один довідник. Модель використовує list_endpoints для пошуку, describe_endpoint щоб дізнатися форму даних, api_call для фактичного виклику API і describe_page_builder, коли завдання стосується вмісту веб-сайту.
list_endpoints
Повертає повний перелік зареєстрованих маршрутів REST з необов'язковим фільтром за підрядком та/або HTTP-методом. Кожен запис містить назву контролера й області доступу ключа API, які найімовірніше знадобляться.
Вхідні дані:
| Поле | Тип | Опис |
|---|---|---|
filter | string (необов'язково) | Підрядок без урахування регістру, який шукається в шляху, наприклад "people" |
method | enum (необов'язково) | GET / POST / PUT / DELETE / PATCH |
Вихідні дані: документ JSON такого вигляду:
{
"total": 24,
"endpoints": [
{
"method": "GET",
"path": "/membership/people",
"controller": "PersonController.getAll",
"likelyScopes": ["people:read", "people:write"]
}
]
}
Перелік формується один раз під час запуску API з актуальної таблиці маршрутів. До будь-якого ендпоїнта, на який можна зробити запит через curl, можна дістатися і звідси.
describe_endpoint
Повертає короткий опис і, де це доступно, вручну підготовлений приклад тіла запиту та відповіді для одного ендпоїнта.
Вхідні дані:
| Поле | Тип | Опис |
|---|---|---|
method | string | HTTP-метод |
path | string | Повний шлях, як його повертає list_endpoints |
Вихідні дані: для ендпоїнтів із прикладами це summary, requestBody і responseSample. Для ендпоїнтів без прикладів це резервне повідомлення, яке радить спершу виконати GET, щоб побачити структуру даних. Близько десятка найчастіше використовуваних маршрутів (люди, групи, пожертви, відвідуваність, фонди) мають приклади.
api_call
Викликає вибраний ендпоїнт REST в межах процесу через той самий стек проміжного програмного забезпечення Express, що й звичайний HTTP-запит. Застосовуються автентифікація, розбір тіла, журналювання аудиту та обмеження за церквою.
Вхідні дані:
| Поле | Тип | Опис |
|---|---|---|
method | enum | GET / POST / PUT / DELETE / PATCH |
path | string | Шлях, включно з префіксом модуля, наприклад /membership/people |
query | object (необов'язково) | Плоский об'єкт параметрів рядка запиту |
body | any (необов'язково) | Тіло запиту у форматі JSON, зазвичай масив об'єктів моделі для POST |
Вихідні дані:
{
"status": 200,
"truncated": false,
"body": [ /* the controller's JSON response */ ]
}
Результат інструмента позначається як isError: true для будь-якої відповіді зі статусом ≥ 400.
describe_page_builder
Єдиний негенеричний інструмент: статичний, самодостатній посібник зі створення сторінок сайту через ендпоїнти /content/*. Він охоплює модель даних Сторінка → Розділ → Елемент, робочий процес створення, кожен elementType із формою answersJSON, налаштування на рівні розділу, зокрема форми-роздільники dividerTop/dividerBottom, а також покроковий приклад від початку до кінця. Інструмент не приймає вхідних даних і відповідає каталогу елементів, який підтримується в редакторі B1Admin (див. Архітектура конструктора веб-сайтів). Агентам рекомендується викликати його один раз перед створенням або редагуванням вмісту сторінки, а далі діяти через api_call.
Модель автентифікації
Сам запит MCP проходить через CustomAuthProvider.getUser(), тобто тим самим шляхом, що й будь-який автентифікований ендпоїнт B1. Bearer-токен cak_… розпізнається як Principal, права якого є поточним RBAC особи, яка випустила ключ, перетнутим з областями доступу, наданими ключу. Цей перетин перераховується при кожному запиті, тож:
- Вилучення області з ключа (шляхом видалення й повторного створення) припиняє доступ під час наступного виклику.
- Вилучення права в базової особи в B1Admin припиняє доступ під час наступного виклику, навіть якщо ключ досі існує.
Для вкладених викликів api_call вихідний заголовок Authorization копіюється у синтетичний запит, тож CustomAuthProvider виконується знову, і перетин областей застосовується для кожного виклику. Кешування токенів немає.
Чорний список шляхів
Деякі маршрути недоступні через api_call, навіть з дійсним ключем:
| Шаблон | Причина |
|---|---|
/giving/donate/webhook/* | Вебхуки провайдерів очікують необроблені тіла з перевіреним підписом від Stripe/PayPal, а не від звичайних викликів |
/membership/oauth/clients* | Реєстрація клієнтів OAuth доступна лише оператору |
/membership/people/apiEmails | Обмежено jwtSecret оператора, а не правами користувача |
Будь-який маршрут, що очікує multipart/form-data | Завантаження файлів не сумісні з JSON-RPC |
Заблокований шлях повертає результат інструмента з isError: true і описовим повідомленням. Базовий маршрут при цьому ніколи не викликається.
Обмеження розміру відповіді
Тіло кожної відповіді api_call обмежено 64 КБ захопленого виводу. Якщо запит перевищує ліміт, відповідь містить "truncated": true, і модель має повторити запит із вужчими параметрами. Так одна відповідь інструмента не заповнює вікно контексту клієнта.
Обмеження швидкості
Для /mcp немає обмеження швидкості на рівні застосунку. У продакшні регулювання відкладено до конкурентності API Gateway та Lambda, а в самостійно розгорнутих системах — до того, що забезпечує ваш зворотний проксі.
Виявлення OAuth
Сервер MCP публікує метадані OAuth 2.1, щоб клієнти, які під'єднуються лише до серверів, знайдених через OAuth, зокрема інтерфейс «Add custom connector» у Claude.ai, могли увійти користувачем без вставленого ключа. /mcp є захищеним ресурсом, провайдер OAuth у /membership/oauth є сервером авторизації, а сторінка /oauth у B1Admin є екраном згоди.
| Ендпоїнт | Призначення |
|---|---|
GET /.well-known/oauth-protected-resource (також /.well-known/oauth-protected-resource/mcp) | Метадані захищеного ресурсу (RFC 9728): resource дорівнює <api>/mcp, authorization_servers є коренем API, а scopes_supported перелічує всі області доступу ключів API |
GET /.well-known/oauth-authorization-server | Метадані сервера авторизації (RFC 8414): authorization_endpoint вказує на /oauth у B1Admin, token_endpoint на /membership/oauth/token, registration_endpoint на /membership/oauth/register |
POST /membership/oauth/register | Динамічна реєстрація клієнта (RFC 7591) |
Послідовність дій, яку виконує клієнт на кшталт claude.ai:
POST /mcpбез токена повертає 401 із заголовкомWWW-Authenticate, що вказує на метадані захищеного ресурсу.- Клієнт читає обидва документи метаданих, а потім реєструється через
POST /membership/oauth/register, надсилаючиclient_name,redirect_urisі, за бажанням,scope. Кожен клієнт, що зареєструвався сам, є публічним: секрет не видається, а у відповідіtoken_endpoint_auth_method: "none". URI перенаправлення мають бутиhttpsабоhttpз адресою зворотної петлі (localhost,127.0.0.1,[::1]), і їх не може бути більше 10 на клієнта. Реєстрація обмежена 20 запитами на годину з однієї IP-адреси. - Користувача спрямовують на
/oauthу B1Admin зcode_challengeіcode_challenge_method=S256. На сторінці згоди кожна запитана область перелічується простою мовою (або з написом «Усе, до чого має доступ ваш обліковий запис B1», якщо нічого не запитано), вказується хост, на який користувача повернуть, і зазначається, якщо застосунок зареєстрував себе сам. Користувач натискає Дозволити. - Клієнт обмінює код на
/membership/oauth/tokenзgrant_type=authorization_codeі своїмcode_verifier, а пізніше оновлює токен зgrant_type=refresh_token. Приймаються як тіла у форматі form-encoded, так і JSON. - Отриманий токен доступу є JWT B1 з обмеженими областями. Він використовується як bearer-токен для
/mcp.
Правила PKCE: приймається лише S256. Клієнт без секрету має надіслати code_challenge під час авторизації та відповідний code_verifier під час обміну токена. Конфіденційні клієнти (із секретом) можуть використовувати лише секрет. URI перенаправлення мають точно збігатися з одним із зареєстрованих.
Клієнти, які приймають статичний bearer-токен у своїй конфігурації, як-от Claude Code, Claude Desktop, OpenAI Agents SDK, Cursor або власний код, можуть і далі використовувати ключ cak_….
Локальна розробка
Ендпоїнт MCP підключається разом з усім іншим, коли API працює локально:
cd Api
npm run dev
# Server listening on http://localhost:8084
Під час запуску рядок журналу 📡 MCP server ready at /mcp — N routes in inventory підтверджує, що перелік сформовано.
Перевірте його за допомогою MCP Inspector:
npx @modelcontextprotocol/inspector
В інтерфейсі Inspector вкажіть http://localhost:8084/mcp і встановіть заголовок Authorization у значення Bearer cak_<prefix>.<secret>. Спершу викличте list_endpoints. Ви маєте побачити повний список маршрутів. Потім api_call({ method: "GET", path: "/membership/people" }) має повернути ваших локальних людей із тестових даних.
Структура коду
Сервер MCP розташований у src/modules/mcp/ у репозиторії Api. Важливі файли:
| Файл | Призначення |
|---|---|
McpController.ts | @controller("/mcp"); для кожного запиту створює StreamableHTTPServerTransport і надсилає виклик WWW-Authenticate у разі 401 |
WellKnownController.ts / OAuthMetadata.ts | Надає документи виявлення OAuth у /.well-known |
McpServer.ts | Створює сервер Server MCP і реєструє чотири інструменти |
RouteInventory.ts | Переглядає метадані inversify-express-utils під час запуску, щоб перелічити маршрути |
internalDispatch.ts | Синтетичні req/res, які повторно входять до застосунку Express у межах процесу |
tools/ | listEndpoints.ts, describeEndpoint.ts, apiCall.ts, describePageBuilder.ts |
examples.ts | Підготовлені приклади запитів і відповідей для найчастіше використовуваних ендпоїнтів |