MCP 서버
B1 API는 /mcp에서 MCP (Model Context Protocol) 서버를 제공합니다. claude.ai 사용자 지정 커넥터, Claude Code, Claude Desktop, OpenAI Agents SDK, Cursor 또는 직접 만든 클라이언트 등 MCP를 지원하는 모든 AI 클라이언트가 이 서버에 연결하여, 인증된 교회 사용자를 대신해 기반 REST API를 호출할 수 있습니다. 이는 얇고 범용적인 래퍼입니다. 각 엔드포인트를 일일이 모델링하는 대신 세 개의 범용 도구로 전체 API 영역을 동적으로 노출하며, 웹사이트 빌더를 위한 도메인 가이드 도구 하나를 추가로 제공합니다.
시작하기 전에
엔드포인트
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 키 범위가 포함됩니다.
입력:
| 필드 | 유형 | 설명 |
|---|---|---|
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 엔드포인트를 일반 HTTP 요청과 동일한 Express 미들웨어 스택을 통해 프로세스 내에서 호출합니다. 인증, 본문 파싱, 감사 로깅, 교회별 범위 지정이 모두 적용됩니다.
입력:
| 필드 | 유형 | 설명 |
|---|---|---|
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 */ ]
}
상태 코드가 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 같은 클라이언트가 수행하는 흐름은 다음과 같습니다.
- 토큰 없이
POST /mcp를 호출하면, 보호된 리소스 메타데이터를 가리키는WWW-Authenticate헤더와 함께 401을 받습니다. - 클라이언트는 두 메타데이터 문서를 읽은 뒤,
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회로 요청 빈도가 제한됩니다. - 사용자는
code_challenge와code_challenge_method=S256을 포함해 B1Admin/oauth로 이동합니다. 동의 페이지는 요청된 각 범위를 쉬운 말로 나열하고(요청된 범위가 없으면 "Everything your B1 account can access"), 사용자가 돌아갈 호스트를 보여주며, 앱이 스스로 등록했을 때 이를 알려줍니다. 사용자는 Allow를 클릭합니다. - 클라이언트는
grant_type=authorization_code와code_verifier로/membership/oauth/token에서 코드를 교환하고, 이후grant_type=refresh_token으로 갱신합니다. 폼 인코딩 본문과 JSON 본문을 모두 받습니다. - 결과 액세스 토큰은 범위가 지정된 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.ts | MCP Server를 만들고 네 개의 도구를 등록합니다 |
RouteInventory.ts | 시작 시 inversify-express-utils 메타데이터를 순회하여 라우트를 열거합니다 |
internalDispatch.ts | 프로세스 내에서 Express 앱으로 다시 들어가는 합성 req/res입니다 |
tools/ | listEndpoints.ts, describeEndpoint.ts, apiCall.ts, describePageBuilder.ts |
examples.ts | 트래픽이 많은 엔드포인트의 큐레이션된 요청/응답 샘플입니다 |