본문으로 건너뛰기

MCP 서버

B1 API는 /mcp에서 MCP (Model Context Protocol) 서버를 제공합니다. claude.ai 사용자 지정 커넥터, Claude Code, Claude Desktop, OpenAI Agents SDK, Cursor 또는 직접 만든 클라이언트 등 MCP를 지원하는 모든 AI 클라이언트가 이 서버에 연결하여, 인증된 교회 사용자를 대신해 기반 REST API를 호출할 수 있습니다. 이는 얇고 범용적인 래퍼입니다. 각 엔드포인트를 일일이 모델링하는 대신 세 개의 범용 도구로 전체 API 영역을 동적으로 노출하며, 웹사이트 빌더를 위한 도메인 가이드 도구 하나를 추가로 제공합니다.

시작하기 전에

  • 클라이언트가 사용할 범위를 가진 B1 API 키(cak_…), 또는 OAuth로 로그인할 수 있는 MCP 클라이언트(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
세션 모델상태 비저장(Stateless). 요청마다 새 MCP 서버 인스턴스를 만들며, 세션 ID와 재개 기능이 없습니다
인증Bearer 토큰. cak_… API 키와 B1 JWT(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는 나머지 엔드포인트에 사용되는 REST API가 아니라 API Gateway HTTP API를 통해 제공됩니다. REST API는 Lambda 프록시 응답에서 WWW-Authenticate를 x-amzn-remapped-www-authenticate로 이름을 바꾸었고, 이 때문에 ChatGPT 같은 클라이언트가 헤더 없는 401만 받아 로그인을 시작할 수 없었습니다. HTTP API는 이 헤더를 변경하지 않고 그대로 전달합니다.

도구​

범용 도구 세 개와 가이드 하나로 구성됩니다. 모델은 탐색에 list_endpoints, 페이로드 형식을 파악하기 위해 describe_endpoint, 실제 API 호출에 api_call을 사용하며, 웹사이트 콘텐츠 작업일 때는 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 메서드
pathstringlist_endpoints가 반환한 전체 경로

출력: 큐레이션된 엔드포인트의 경우 summary, requestBody, responseSample이 포함된 예시를 반환합니다. 큐레이션되지 않은 엔드포인트의 경우, 먼저 GET을 호출해 형식을 확인하라는 대체 메시지를 반환합니다. 트래픽이 많은 열 개 정도의 경로(사람, 그룹, 헌금, 출석, 펀드)가 큐레이션되어 있습니다.

api_call​

선택한 REST 엔드포인트를 일반 HTTP 요청과 동일한 Express 미들웨어 스택을 통해 프로세스 내에서 호출합니다. 인증, 본문 파싱, 감사 로깅, 교회별 범위 지정이 모두 적용됩니다.

입력:

필드유형설명
methodenumGET / POST / PUT / DELETE / PATCH
pathstring모듈 접두사를 포함한 경로. 예: /membership/people
queryobject (선택)쿼리 문자열 매개변수의 평면 객체
bodyany (선택)JSON 요청 본문. 일반적으로 POST에는 모델 객체의 배열을 사용합니다

출력:

{
"status": 200,
"truncated": false,
"body": [ /* the controller's JSON response */ ]
}

상태 코드가 400 이상인 응답에는 도구 결과에 isError: true가 표시됩니다.

describe_page_builder​

일반 도구가 아닌 유일한 도구입니다. /content/* 엔드포인트를 통해 웹사이트 페이지를 만드는 방법을 설명하는 정적이며 독립적인 가이드입니다. Page → Section → Element 데이터 모델, 생성 작업 흐름, 각 elementType과 answersJSON 형식, dividerTop/dividerBottom 모양 구분선 같은 섹션 수준 설정, 그리고 전체 과정을 보여주는 예시를 포함합니다. B1Admin 편집기에서 관리하는 요소 목록을 그대로 반영합니다(웹사이트 빌더 아키텍처 참고). 에이전트는 페이지 콘텐츠를 만들거나 편집하기 전에 한 번 호출한 뒤, api_call로 작업하도록 되어 있습니다.

인증 모델​

MCP 요청 자체는 CustomAuthProvider.getUser()를 거칩니다. 이는 인증이 필요한 모든 B1 엔드포인트가 사용하는 것과 같은 경로입니다. cak_… Bearer 토큰은 Principal로 해석되며, 이 주체의 권한은 키를 발급한 사람의 현재 RBAC 권한을 키에 부여된 범위와 **교차(intersection)**한 결과입니다. 이 교차 계산은 요청마다 다시 수행되므로 다음이 적용됩니다.

  • 키에서 범위를 제거(키를 삭제하고 다시 만드는 방식)하면, 다음 호출부터 접근이 차단됩니다.
  • 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 KB까지만 허용됩니다. 쿼리가 제한을 넘으면 응답에 "truncated": true가 포함되며, 모델은 더 좁은 쿼리 매개변수로 다시 시도해야 합니다. 이렇게 하면 단일 도구 응답이 클라이언트의 컨텍스트 창을 넘치게 하는 일을 막을 수 있습니다.

요청 빈도 제한​

/mcp에는 애플리케이션 수준의 요청 빈도 제한이 없습니다. 운영 환경에서는 API Gateway / Lambda 동시성으로 조절하며, 자체 호스팅 배포에서는 리버스 프록시가 적용하는 제한에 따릅니다.

OAuth 탐색​

MCP 서버는 OAuth 2.1 메타데이터를 공개하므로, OAuth로 발견된 서버에만 연결하는 클라이언트(특히 Claude.ai의 "Add custom connector" UI)가 키를 붙여 넣지 않고도 사용자를 로그인시킬 수 있습니다. /mcp는 보호된 리소스이고, /membership/oauth 아래의 OAuth 제공자가 권한 서버이며, B1Admin의 /oauth 페이지가 동의 화면입니다.

엔드포인트용도
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는 B1Admin /oauth, token_endpoint는 /membership/oauth/token, registration_endpoint는 /membership/oauth/register입니다
POST /membership/oauth/register동적 클라이언트 등록(RFC 7591)

claude.ai 같은 클라이언트가 수행하는 흐름은 다음과 같습니다.

  1. 토큰 없이 POST /mcp를 호출하면, 보호된 리소스 메타데이터를 가리키는 WWW-Authenticate 헤더와 함께 401을 받습니다.
  2. 클라이언트는 두 메타데이터 문서를 읽은 뒤, client_name, redirect_uris와 선택 항목인 scope를 보내 POST /membership/oauth/register로 자신을 등록합니다. 자체 등록된 모든 클라이언트는 공개(public) 클라이언트입니다. 비밀 값은 발급되지 않으며, 응답에는 token_endpoint_auth_method: "none"이 포함됩니다. 리디렉션 URI는 https이거나, 루프백 주소(localhost, 127.0.0.1, [::1])의 http여야 하며, 클라이언트당 최대 10개입니다. 등록은 IP당 시간당 20회로 요청 빈도가 제한됩니다.
  3. 사용자는 code_challenge와 code_challenge_method=S256을 포함해 B1Admin /oauth로 이동합니다. 동의 페이지는 요청된 각 범위를 쉬운 말로 나열하고(요청된 범위가 없으면 "Everything your B1 account can access"), 사용자가 돌아갈 호스트를 보여주며, 앱이 스스로 등록했을 때 이를 알려줍니다. 사용자는 Allow를 클릭합니다.
  4. 클라이언트는 grant_type=authorization_code와 code_verifier로 /membership/oauth/token에서 코드를 교환하고, 이후 grant_type=refresh_token으로 갱신합니다. 폼 인코딩 본문과 JSON 본문을 모두 받습니다.
  5. 결과 액세스 토큰은 범위가 지정된 B1 JWT이며, /mcp의 Bearer 토큰으로 사용됩니다.

PKCE 규칙: S256만 허용됩니다. 비밀 값이 없는 클라이언트는 인가 요청에 code_challenge를, 토큰 교환에 일치하는 code_verifier를 보내야 합니다. 기밀 클라이언트(비밀 값이 있는 경우)는 비밀 값만으로도 사용할 수 있습니다. 리디렉션 URI는 등록된 URI와 정확히 일치해야 합니다.

설정에서 정적 Bearer 토큰을 받는 클라이언트(Claude Code, Claude Desktop, OpenAI Agents SDK, Cursor, 사용자 정의 코드)는 계속해서 cak_… 키를 사용할 수 있습니다.

로컬 개발​

로컬에서 API를 실행하면 MCP 엔드포인트도 다른 기능과 함께 마운트됩니다.

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 UI에서 http://localhost:8084/mcp를 지정하고, Authorization 헤더를 Bearer cak_<prefix>.<secret>로 설정합니다. 먼저 list_endpoints를 호출하면 전체 라우트 목록이 보여야 합니다. 그다음 api_call({ method: "GET", path: "/membership/people" })를 호출하면 로컬 시드 사람 데이터가 반환되어야 합니다.

코드 구조​

MCP 서버는 Api 저장소의 src/modules/mcp/에 있습니다. 주요 파일은 다음과 같습니다.

파일용도
McpController.ts@controller("/mcp"); 요청마다 StreamableHTTPServerTransport를 연결하고 401 시 WWW-Authenticate 인증 요구를 보냅니다
WellKnownController.ts / OAuthMetadata.ts/.well-known OAuth 탐색 문서를 제공합니다
McpServer.tsMCP Server를 만들고 네 개의 도구를 등록합니다
RouteInventory.ts시작 시 inversify-express-utils 메타데이터를 순회하여 라우트를 열거합니다
internalDispatch.ts프로세스 내에서 Express 앱으로 다시 들어가는 합성 req/res입니다
tools/listEndpoints.ts, describeEndpoint.ts, apiCall.ts, describePageBuilder.ts
examples.ts트래픽이 많은 엔드포인트의 큐레이션된 요청/응답 샘플입니다

관련 문서​