Сервер MCP
B1 API предоставляет сервер 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) - Доступный хост B1 API —
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-токен. Ключи API 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 | строка (необязательно) | Подстрока без учета регистра, которая сопоставляется с путем, например "people" |
method | перечисление (необязательно) | 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 | строка | HTTP-метод |
path | строка | Полный путь, как его возвращает list_endpoints |
Выходные данные: для подготовленных эндпоинтов — пример с summary, requestBody и responseSample. Для эндпоинтов без подготовленного примера — резервное сообщение с инструкцией сначала вызвать GET, чтобы увидеть форму данных. Около десятка часто используемых маршрутов (люди, группы, пожертвования, посещаемость, фонды) подготовлены заранее.
api_call
Вызывает выбранный REST-эндпоинт внутри процесса, через тот же стек промежуточного ПО Express, что и обычный HTTP-запрос — применяются авторизация, разбор тела, журнал аудита и ограничение по церкви.
Входные данные:
| Поле | Тип | Описание |
|---|---|---|
method | перечисление | GET / POST / PUT / DELETE / PATCH |
path | строка | Путь, включая префикс модуля, например /membership/people |
query | объект (необязательно) | Плоский объект параметров строки запроса |
body | любой (необязательно) | Тело запроса в JSON — обычно массив объектов модели для POST |
Выходные данные:
{
"status": 200,
"truncated": false,
"body": [ /* the controller's JSON response */ ]
}
Результат инструмента помечается как isError: true для любого ответа со статусом ≥ 400.
describe_page_builder
Единственный неуниверсальный инструмент: статическое самодостаточное руководство по созданию страниц сайта через эндпоинты /content/* — модель данных Page → Section → Element, порядок создания, каждый 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на loopback-адресе (localhost,127.0.0.1,[::1]); не более 10 на клиента. Регистрация ограничена 20 запросами в час с одного IP. - Пользователя отправляют на страницу
/oauthв B1Admin сcode_challengeиcode_challenge_method=S256. Страница согласия перечисляет каждую запрошенную область простым языком (или «Everything your B1 account can access», если области не запрошены), показывает хост, на который пользователь вернется, и отмечает, когда приложение зарегистрировало себя само. Пользователь нажимает Allow. - Клиент обменивает код на
/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 перенаправления должны точно совпадать с зарегистрированным 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 | Создает MCP Server и регистрирует четыре инструмента |
RouteInventory.ts | Обходит метаданные inversify-express-utils при запуске, чтобы перечислить маршруты |
internalDispatch.ts | Синтетические req/res, которые повторно входят в приложение Express внутри процесса |
tools/ | listEndpoints.ts, describeEndpoint.ts, apiCall.ts, describePageBuilder.ts |
examples.ts | Подготовленные примеры запросов и ответов для часто используемых эндпоинтов |