mcp-resource-server

10개의 모의 업종(뱅킹, 헬스케어, 정부, 제조, 소매, 스포츠용품, 대학, 인력, Abercrombie & Fitch, 항공)에 걸친 읽기 전용 도구와 투자 도구 세트를 노출하는 MCP 서버입니다. 각 업종은 자체 번들 SQLite 데이터베이스를 읽습니다 — 실행에 다른 서비스가 필요하지 않습니다. 투자 도구는 선택적으로 사용자가 제공하는 뱅킹 API에 프록시할 수 있습니다(아래 참조).

사전 요구 사항

• Docker + Docker Compose

• 베어러 토큰을 발급하고 검증할 PingOne 환경(또는 올바른 aud/scope 클레임이 있는 JWT를 발급하고 JWKS 엔드포인트를 게시할 수 있는 모든 OAuth AS — 이 서버는 표준 OIDC 디스커버리만 사용하며 PingOne 고유의 기능에 의존하지 않습니다)

Related MCP server: mock-mcp

빠른 시작

cp .env.example .env

.env를 편집합니다: 자신의 PingOne 환경에 맞게 MCP_RESOURCE_SERVER_RESOURCE_URI, PINGONE_ENVIRONMENT_ID, PINGONE_REGION을 설정합니다. 실제 토큰을 확보할 때까지 PINGONE_ISSUER는 주석 처리된 상태로 둡니다("인증 모드" 참조).

docker compose up --build

서버는 http://localhost:8081에서 수신 대기합니다. SQLite 데이터베이스는 ./data에 유지됩니다(최초 사용 시 seed/에서 시드됨; 재시작 시 비어 있지 않은 데이터베이스를 다시 시드하지 않음).

실행 확인

curl http://localhost:8081/health
curl http://localhost:8081/.well-known/oauth-protected-resource

두 번째 호출은 리소스의 광고된 스코프와, PINGONE_ENVIRONMENT_ID/PINGONE_REGION이 설정된 경우 해당 인증 서버를 반환합니다 — MCP 클라이언트가 OAuth 디스커버리에 사용하는 RFC 9728 메타데이터입니다.

인증 모드

토큰 서명이 검증되는지 여부는 JWKS 소스가 구성되었는지에 따라 결정됩니다 — STRICT_AUTH가 아닙니다:

• JWKS 소스 설정됨 (PINGONE_ISSUER, PINGONE_JWKS_URI, 또는 PINGONE_BASE_URL) — 모든 토큰은 PingOne 환경의 키로 검증되며 실패 시 거부됩니다. STRICT_AUTH는 효과가 없습니다. 실제 토큰이 흐르기 시작하면 이 방식으로 실행합니다.

• JWKS 소스 없음 — STRICT_AUTH=false(기본 제공 값)는 콘솔 경고와 함께 형식이 올바른 토큰을 수락하므로, PingOne을 연결하기 전에 수제 토큰으로 모든 도구를 실행해볼 수 있습니다. STRICT_AUTH=true는 대신 모든 토큰을 거부합니다. 기본값을 필요한 이상으로 많은 사람이 접근할 수 있게 두지 마십시오.

.env.example에는 이러한 이유로 세 개의 JWKS 변수가 모두 주석 처리되어 제공됩니다 — 실제 토큰이 있으면 하나의 주석을 해제하십시오.

베어러 토큰 얻기

모든 도구 호출에는 aud 클레임이 MCP_RESOURCE_SERVER_RESOURCE_URI와 일치하고 scope 클레임이 호출하는 도구를 포함하는 베어러 토큰이 필요합니다(권위 있는 최신 목록은 tools/list 참조 — 이 서버 자체 레지스트리에서 생성됨).

로컬 테스트 (STRICT_AUTH=false) — 올바른 클레임이 있는 형식이 올바른 JWT면 충분합니다. 서명은 확인되지 않습니다.

node -e "
const b64 = s => Buffer.from(JSON.stringify(s)).toString('base64url');
const header = b64({alg:'none',typ:'JWT'});
const payload = b64({sub:'test-user',scope:'airlines:read',aud:'your-resource-uri',exp:Math.floor(Date.now()/1000)+3600});
console.log(header+'.'+payload+'.');
"

(aud를 자신의 MCP_RESOURCE_SERVER_RESOURCE_URI 값으로 바꾸고, scope를 테스트 중인 도구로 바꾸십시오)

실제 토큰 (STRICT_AUTH=true) — PingOne 환경에서 발급합니다. PingOne 토큰 엔드포인트에 대한 클라이언트 자격 증명 부여로, 이 서버의 오디언스를 리소스로 요청합니다:

curl -s -X POST "https://auth.pingone.<region>/<env-id>/as/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<your PingOne worker app client id>" \
  -d "client_secret=<your PingOne worker app client secret>" \
  -d "scope=<space-separated scopes, e.g. banking:read airlines:read>" \
  -d "resource=<MCP_RESOURCE_SERVER_RESOURCE_URI value>"

이를 위해서는 해당 클라이언트의 앱이 PingOne에서 이 리소스와 해당 스코프에 대해 권한이 부여되어야 합니다(Applications → your app → Resources) — 이 서버가 대신 해주지 않는 PingOne 측 설정 단계입니다.

도구 직접 호출(기본 확인)

TOKEN="<paste a token from above>"
curl -s -X POST http://localhost:8081/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_airline_bookings","arguments":{}}}'

MCP 클라이언트 연결

서버는 동일한 포트에서 WebSocket과 HTTP(스트리밍 가능, POST /mcp)로 MCP를 지원합니다 — ws://localhost:8081 또는 http://localhost:8081/mcp.

MCP Inspector (공식 개발 도구 — 모든 서버에서 작동하며 수동 헤더를 설정할 수 있으므로 이 서버를 테스트하는 가장 안정적인 방법입니다):

npx @modelcontextprotocol/inspector

Transport를 "Streamable HTTP"로, URL을 http://localhost:8081/mcp로 설정하고, 연결 전에 Inspector의 연결 설정에 Authorization: Bearer <token> 헤더를 추가하십시오.

Claude Desktop / Cursor / Windsurf (정적 구성, HTTP 전송):

{
  "mcpServers": {
    "mcp-resource-server": {
      "url": "http://localhost:8081/mcp",
      "transport": "http"
    }
  }
}

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json

• Cursor: 프로젝트 루트의 .cursor/mcp.json

• Windsurf: ~/.codeium/windsurf/mcp_config.json

이 구성에는 정적 베어러 토큰 필드가 없습니다 — 클라이언트가 보호된 도구를 호출하면 /.well-known/oauth-protected-resource를 읽고, PingOne 환경을 인증 서버로 찾아 로그인을 요청합니다. 이는 PingOne 환경에 해당 특정 MCP 클라이언트 앱에 대해 등록된 OAuth 클라이언트가 있고, 해당 클라이언트 자체 문서에 지정된 리디렉션 URI를 사용할 때만 작동합니다 — 이 서버 외부의 PingOne 측 설정 단계입니다. 구성 편집 후 클라이언트를 다시 시작하십시오.

투자 도구

get_investment_accounts, get_investment_balance, get_portfolio_summary, get_investment_transactions는 다른 모든 업종과 마찬가지로 번들 SQLite 데이터베이스(data/invest.db, 최초 사용 시 seed/invest.seed.json에서 시드됨)에서 즉시 작동합니다.

자체 뱅킹 API를 실행 중이고 이 네 가지 도구가 호출자의 베어러 토큰을 해당 API로 전달하고 반환된 결과를 그대로 반환하도록 하려는 경우에만 BANKING_API_BASE_URL을 설정하십시오. 설정된 경우 번들 투자 데이터베이스는 사용되지 않습니다.

도구 추가

도구는 구성이 아닌 코드입니다. 카탈로그(tools/list), 도구별 스코프 게이트, /.well-known/oauth-protected-resource에 광고된 scopes_supported는 모두 src/tools/registry.ts의 ALL_TOOLS에서 파생되므로, 업종 목록에 추가한 도구는 이미지를 다시 빌드하면 모든 곳에서 활성화됩니다(빠른 시작의 --build 명령).

1. 기존 업종에 도구 추가

레지스트리 변경 없이 두 가지 수정만 하면 됩니다:

1. 해당 업종의 src/tools/<vertical>Tools.ts 배열에 도구 정의를 추가합니다. 예: sportingGoodsTools.ts:

   {
     name: 'gear_return_status',
     description: 'Show the status of a sporting-goods return.',
     inputSchema: {
       type: 'object',
       properties: { orderId: { type: 'string', description: 'Order ID' } },
       required: ['orderId'],
     },
     requiredScopes: ['read'],   // the bearer token must carry every scope listed
     readOnly: true,
     intentHints: ['check my gear return'],   // required — tests/registry.test.ts asserts it
   },

2. src/tools/<vertical>ToolHandler.ts의 switch에 일치하는 case 'gear_return_status':를 추가합니다. 핸들러는 JSON만 반환합니다 — 해당 업종의 src/db/<vertical>Db.ts에서 읽거나 다른 것을 사용합니다.

2. 새 업종 추가

위와 동일한 두 파일(src/tools/<vertical>Tools.ts에서 <VERTICAL>_TOOLS: McpToolDef[] 내보내기, src/tools/<vertical>ToolHandler.ts에서 dispatch<Vertical>Tool 내보내기)에 더해:

• 데이터 (선택 사항): src/db/<vertical>Db.ts + seed/<vertical>.seed.json. sportingGoodsDb.ts를 복사하십시오 — data/<vertical>.db를 열고, 스키마를 생성하고, 테이블이 비어 있을 때만 시드를 적용합니다. Dockerfile은 이미 seed/를 복사하고, compose 파일은 이미 data/를 마운트합니다.

• 등록 src/tools/registry.ts에서: 두 내보내기를 가져오고, <VERTICAL>_TOOLS를 ALL_TOOLS에 펼치고, const <VERTICAL>_TOOL_NAMES = new Set(<VERTICAL>_TOOLS.map((t) => t.name))을 추가하고, dispatch()에 한 줄을 추가합니다: if (<VERTICAL>_TOOL_NAMES.has(toolName)) return dispatch<Vertical>Tool(toolName, args, subject); (subject는 토큰의 sub입니다 — 뱅킹과 항공처럼 읽기가 호출자로 범위가 지정되어야 하는 경우 핸들러에서 이를 수락하십시오.)

• 리소스 (선택 사항): tools/list는 자동이지만, MCP 리소스(resources/list, resources/read)는 src/index.ts의 수동 유지 관리 RESOURCE_CATALOG에서 가져옵니다 — 업종이 목록 도구를 리소스로도 노출해야 하는 경우 해당 항목을 추가하십시오.

주의할 점

• requiredScopes는 PingOne 리소스가 실제로 부여하는 스코프여야 합니다. 그중 하나라도 누락된 토큰은 tools/call에서 403을 받고, tools/list는 해당 토큰에서 도구를 완전히 숨깁니다.

• 도구 이름은 전역입니다. dispatch()는 일치하는 첫 번째 이름 집합으로 라우팅하므로, 두 업종에서 이름을 재사용하면 먼저 확인되는 쪽으로 조용히 이동합니다.

• 템플릿으로 invest가 아닌 데이터 기반 업종(예: 스포츠용품)을 사용하십시오 — invest는 dispatch() 폴스루이며 필요하지 않은 프록시 대 SQLite 스위치를 포함합니다.