Перейти к основному содержимому

Сервер 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:

  1. POST /mcp без токена возвращает 401 с заголовком WWW-Authenticate, указывающим на метаданные защищенного ресурса.
  2. Клиент читает оба документа метаданных, затем регистрируется через 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.
  3. Пользователя отправляют на страницу /oauth в B1Admin с code_challenge и code_challenge_method=S256. Страница согласия перечисляет каждую запрошенную область простым языком (или «Everything your B1 account can access», если области не запрошены), показывает хост, на который пользователь вернется, и отмечает, когда приложение зарегистрировало себя само. Пользователь нажимает Allow.
  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 перенаправления должны точно совпадать с зарегистрированным 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Подготовленные примеры запросов и ответов для часто используемых эндпоинтов

Связанные материалы​