Перейти до основного вмісту

Сервер 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, які найімовірніше знадобляться.

Вхідні дані:

ПолеТипОпис
filterstring (необов'язково)Підрядок без урахування регістру, який шукається в шляху, наприклад "people"
methodenum (необов'язково)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​

Повертає короткий опис і, де це доступно, вручну підготовлений приклад тіла запиту та відповіді для одного ендпоїнта.

Вхідні дані:

ПолеТипОпис
methodstringHTTP-метод
pathstringПовний шлях, як його повертає list_endpoints

Вихідні дані: для ендпоїнтів із прикладами це summary, requestBody і responseSample. Для ендпоїнтів без прикладів це резервне повідомлення, яке радить спершу виконати GET, щоб побачити структуру даних. Близько десятка найчастіше використовуваних маршрутів (люди, групи, пожертви, відвідуваність, фонди) мають приклади.

api_call​

Викликає вибраний ендпоїнт REST в межах процесу через той самий стек проміжного програмного забезпечення Express, що й звичайний HTTP-запит. Застосовуються автентифікація, розбір тіла, журналювання аудиту та обмеження за церквою.

Вхідні дані:

ПолеТипОпис
methodenumGET / POST / PUT / DELETE / PATCH
pathstringШлях, включно з префіксом модуля, наприклад /membership/people
queryobject (необов'язково)Плоский об'єкт параметрів рядка запиту
bodyany (необов'язково)Тіло запиту у форматі 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:

  1. POST /mcp без токена повертає 401 із заголовком WWW-Authenticate, що вказує на метадані захищеного ресурсу.
  2. Клієнт читає обидва документи метаданих, а потім реєструється через 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-адреси.
  3. Користувача спрямовують на /oauth у B1Admin з code_challenge і code_challenge_method=S256. На сторінці згоди кожна запитана область перелічується простою мовою (або з написом «Усе, до чого має доступ ваш обліковий запис B1», якщо нічого не запитано), вказується хост, на який користувача повернуть, і зазначається, якщо застосунок зареєстрував себе сам. Користувач натискає Дозволити.
  4. Клієнт обмінює код на /membership/oauth/token з grant_type=authorization_code і своїм code_verifier, а пізніше оновлює токен з grant_type=refresh_token. Приймаються як тіла у форматі form-encoded, так і JSON.
  5. Отриманий токен доступу є 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Підготовлені приклади запитів і відповідей для найчастіше використовуваних ендпоїнтів

Пов'язане​