MCP Bifrost

Multi-workspace MCP bridge. Aggregate any number of MCP servers (stdio / Streamable HTTP / SSE) behind one endpoint, register the same upstream service multiple times with different tokens, and expose them to claude.ai / Claude Code / Palantir as namespaced tools (github_personal__create_issue). OAuth 2.0 with workspace-scoped DCR isolation, multi-tenant MCP tokens with profiles, and a built-in admin SPA. English docs are limited — Korean docs and the REST/MCP route names below are the current reference.

Multi-workspace MCP bridge — 임의의 MCP 서버(stdio/HTTP/SSE)를 단일 엔드포인트로 통합하는 범용 허브.

[Filesystem MCP] ──┐
[GitHub MCP]     ──┤
[Notion (공식)]   ──┼→ MCP Bifrost (HTTPS) ←→ claude.ai / Claude Code / Palantir
[회사 Slack]     ──┤      :3100
[Linear]         ──┘

왜 Bifrost?

• MCP 서버 1개당 클라이언트 1개 제약을 우회 — 한 곳에 다 모아서 단일 엔드포인트로 노출
• 같은 MCP 서버를 여러 토큰/계정으로 동시 등록 (개인 GitHub + 회사 GitHub)
• 네임스페이스로 충돌 방지: github_personal__create_issue vs github_work__create_issue
• claude.ai 원격 커넥터 호환 (SSE), Claude Code .mcp.json 자동 생성

Quick Start

npm install
npm start
# → http://localhost:3100/admin/  (Setup Wizard 자동 진입)

5분 가이드: docs/QUICKSTART.md · 상세 사용법: docs/USAGE.md.

Architecture

server/
  index.js              — HTTP/SSE 서버 진입점 (단일 포트 :3100)
  mcp-handler.js        — MCP JSON-RPC (initialize, tools/list, tools/call, resources/*)
  workspace-manager.js  — 워크스페이스 CRUD, 원자적 쓰기, hot reload, 5단계 상태
  tool-registry.js      — 네임스페이스 + 역방향 lookup 테이블
  sse-manager.js        — SSE 세션 + notifications/tools/list_changed broadcast

providers/
  base.js               — Provider 추상 인터페이스
  mcp-client.js         — 범용 MCP 클라이언트 (stdio/http/sse) ★ 1등 시민
  notion.js             — Notion REST 어댑터 (legacy)
  slack.js              — Slack REST 어댑터 (legacy)

admin/
  auth.js               — Admin/MCP 토큰 검증, command whitelist
  routes.js             — REST API + 정적 파일 서빙
  public/               — Vanilla SPA (Login, Wizard, Dashboard, Detail, Tools, Connect)

scripts/
  tunnel.js             — Cloudflare Tunnel 통합 + .mcp.json 자동 생성

tests/
  fixtures/mock-mcp-server.js — 테스트용 stdio MCP 서버
  *.test.js                   — 41개 파일 / 426개 테스트 (node --test)

주요 개념

개념	설명
kind	mcp-client(범용) 또는 native(Notion/Slack 직접 어댑터, legacy)
transport	mcp-client 의 연결 방식: stdio / http / sse
namespace	MCP 도구 이름의 일부, 불변 (github_personal__create_issue 의 personal)
alias / displayName	UI 표시용, 자유 변경
toolFilter	워크스페이스별 도구 화이트리스트
profile	/mcp?profile=read-only 처럼 클라이언트별 도구셋 제한

Status

• ✅ MCP 프로토콜 (Streamable HTTP + SSE)
• ✅ 범용 MCP 클라이언트 (stdio/HTTP/SSE)
• ✅ 워크스페이스 CRUD + soft delete + restore + 마이그레이션
• ✅ 5단계 상태 (Healthy/Limited/Action Needed/Error/Disabled)
• ✅ 자동 재시작 + exponential backoff
• ✅ Admin UI (Wizard, Dashboard, Detail, Tools Overview, Connect Guide)
• ✅ 템플릿 라이브러리 (Filesystem, GitHub, Notion, ...)
• ✅ Cloudflare Tunnel + .mcp.json 자동 생성
• ✅ OAuth 2.0 for remote MCP (Notion 공식, PKCE, DCR, refresh rotation, mutex)
• ✅ Multi-tenant (Phase 7) — byIdentity OAuth 격리, 다중 MCP 토큰 + ACL, 프로필, 사용량/감사 로그
• ✅ OAuth Client Isolation (Phase 10a) — workspace 단위 DCR client 격리, 401 fail-fast, FIFO chain mutex (_identityMutex + _workspaceMutex), migration 스크립트. Codex 11 rounds APPROVE.
• ✅ Phase 11 — Phase 10a 수렴 + 관측성 + hardening (10 sub-phases, Codex 15 rounds, 0 open). 자세한 내용은 docs/PHASE11_SELFREVIEW_LOG.md
  • OAuthMetrics 본격 구현 + GET /api/oauth/metrics / GET /api/oauth/metrics/status (saturation)
  • Refresh timeout + AbortController (state/audit convergence)
  • Cache key schema ws:: / global:: (legacy 자동 마이그레이션)
  • Watcher rename 이벤트 수용 (atomic-replace 에디터 호환)
  • Admin Wizard static-client UX (provider 별 가이드 + copyable redirect URI)
• ✅ 426 tests passing (428 total, 2 skipped)

다중 사용자 운영 (Phase 7)

Phase 7 부터 여러 MCP 토큰 + 토큰별 OAuth 격리 를 지원합니다. 기존 단일 사용자 배포는 추가 설정 없이 그대로 동작합니다.

• MCP 토큰 발급: Admin UI "Tokens" 탭에서 + Issue Token → 토큰별 allowedWorkspaces / allowedProfiles glob 지정. 발급 시 plaintext 가 1회만 노출되며 저장은 scrypt 해시. 레거시 BIFROST_MCP_TOKEN (단수) 은 identity=legacy, 전체 허용으로 계속 동작.
• OAuth 격리: 같은 워크스페이스에 여러 identity 를 authorize 가능. 토큰별 byIdentity[identity].tokens 로 저장, refresh mutex 도 identity 별로 독립. A identity 의 refresh_token 은 B 가 접근 불가.
• 프로필: /mcp?profile=read-only 등으로 도구/워크스페이스 glob 필터. config/workspaces.json > server.profiles 또는 Admin UI "Profiles" 탭에서 편집.
• 사용량 / 감사: .ao/state/usage.jsonl + audit.jsonl (chmod 0600, 10MB 로테이션, 30일 보관). Admin UI "Usage" / "Audit" 탭에서 조회.

보안 주의사항 (선택)

• 토큰 파일은 POSIX 에서 chmod 0600. Windows 는 OS 수준 보호가 제한적이므로 공유 PC 사용 자제.
• 단일 사용자 환경에서도 BIFROST_MCP_TOKEN 을 설정해 익명 접근을 차단할 것.
• 원격 노출 (Cloudflare Tunnel 등) 시 MCP 토큰 필수. Admin UI 는 기본적으로 localhost 전용, BIFROST_ADMIN_EXPOSE=1 로만 외부 노출.

관측성

• 로그 레벨: BIFROST_LOG_LEVEL=error|warn|info|debug (기본 info). MCP stream 연결/재연결 전이 같은 상세 이벤트는 debug 에서만 노출. 운영 환경은 기본값 유지 권장.
• OAuth 카운터: GET /api/oauth/metrics 가 [{name, labels, value}] snapshot 을 반환 (oauth_dcr_total, oauth_refresh_total, oauth_threshold_trip_total, oauth_cache_hit/miss_total). 인메모리 only 라 process 재시작 시 초기화.
• 카운터 saturation: GET /api/oauth/metrics/status 가 {entries, maxEntries, capped, evictionsTotal, saturation} 을 반환. cardinality 추이 모니터링용. soft cap 기본 10_000 (new OAuthMetrics({ maxEntries }) 로 조정 가능).
• OAuth audit 이벤트: GET /api/oauth/audit (토큰 prefix + 메타만 기록).
• 파일 권한 경고: GET /api/oauth/security 가 Windows 등에서 chmod 0600 적용 실패 여부를 surface.

License

MIT