요약 (TL;DR)

MCP 서버는 강력하지만, 팀 내 누구나 가드레일 없이 연결하여 도구를 실행할 수 있다면 운영 시스템(production systems)을 노출시킬 위험이 있습니다.

신입 사원이 자신의 노트북에서 앱을 테스트하다가 실수로 MCP 서버에 운영 데이터베이스(production database)에 대한 액세스 권한을 부여하는 상황을 상상해 보세요. 거버넌스(governance)가 없다면, 이는 데이터 유출로 이어지는 현실적인 경로가 됩니다.

Bifrost는 세 가지 계층을 통해 이 문제를 해결합니다:

1. Human-in-the-loop 실행 — Bifrost는 도구 호출을 자동으로 실행하지 않습니다. LLM은 도구를 _제안(suggest)_할 뿐이며, 여러분의 애플리케이션이 이를 검토한 후 명시적으로 POST /v1/mcp/tool/execute를 호출해야 합니다.
2. 기본 차단 방식(Deny-by-default)의 도구 필터링 — mcp_configs가 없는 가상 키(virtual key)는 MCP 도구를 전혀 사용할 수 없습니다. 목록에 없는 클라이언트는 암묵적으로 차단됩니다.
3. 거버넌스 (선택 사항) — RBAC (역할 기반 액세스 제어), SSO (단일 로그인), 감사 로그(audit logs), 그리고 MCP 도구 그룹(MCP Tool Groups)을 통해 누가 게이트웨이를 구성하고 관리 활동을 검토할 수 있는지 제어합니다.

Bifrost는 가상 키, 예산, 속도 제한(rate limits), 라우팅, MCP 도구 필터링, RBAC, SSO, 감사 로그 및 MCP 도구를 다룹니다.

🔧 MCP 서버 사용하기

먼저, 앱을 열고 MCP 서버를 설정해 보겠습니다. 이를 위해 터미널에 다음 명령어를 입력하겠습니다:

npx -y @maximhq/bifrost

그 후, 다음과 같은 인터페이스가 나타납니다 (버전에 따라 유사할 수 있음):

"MCP Library" 탭으로 이동하면 프로젝트에서 사용할 수 있도록 사전 구성된 방대한 MCP 서버 목록을 볼 수 있습니다.

자신만의 MCP 서버를 설정하려면, MCP Gateway로 이동하여 New MCP Server를 클릭하세요:

여기에서 연결 URL (connection URL), 인증 유형 (auth type), 도구 허용 목록 (tool allowlists), 그리고 많은 MCP 서버를 오케스트레이션 (orchestrating)할 때 토큰 사용량을 크게 줄일 수 있는 Code Mode를 포함한 기타 설정을 지정할 수 있습니다.

💎 Star Bifrost ☆

⚙️ Human-in-the-loop 도구

이것은 서론에서 언급한 시나리오를 위한 가장 중요한 보안 속성입니다.

LLM이 도구 호출 (tool calls)을 반환할 때, Bifrost는 이를 자동으로 실행하지 않습니다. 도구 호출은 단지 제안일 뿐입니다. 귀하의 애플리케이션은 각 호출을 명시적으로 승인하고 실행해야 합니다:

1. POST /v1/chat/completions   → LLM이 도구 호출 제안을 반환함 (실행되지 않음)
2. 귀하의 앱이 도구 호출을 검토함 → 보안 규칙 적용, 필요한 경우 사용자 승인 획득
3. POST /v1/mcp/tool/execute   → 승인된 도구 호출을 명시적으로 실행
...

실행 호출 예시:

curl -X POST http://localhost:8080/v1/mcp/tool/execute \
  -H "Content-Type: application/json" \
  -d '{
...

따라서 신입 사원의 에이전트가 위험한 데이터베이스 작업을 _요청_하더라도, 귀하의 애플리케이션이 의도적으로 실행하기 전까지는 아무 일도 일어나지 않습니다. 아래에 설명된 기본 거부 방식 (deny-by-default)의 가상 키 필터링과 결합하여, 이것이 실수로 인한 운영 환경 접근에 대한 Bifrost의 진정한 3계층 해답입니다.

Agent Mode를 통해 특정 도구에 대해 자율 실행 (autonomous execution)을 선택할 수 있지만, 이는 반드시 명시적으로 구성해야 하며 기본값은 아닙니다.

💻 MCP 인증

인증은 MCP 클라이언트 자체에서 최상위 auth_type 필드로 선언되며, /api/mcp/client로 전송됩니다. 중첩된 auth 객체는 존재하지 않습니다.

OAuth (oauth 및 per_user_oauth)는 HTTP 및 SSE 연결에서만 유효합니다. Bifrost는 Authorization Code (인증 코드) 플로우를 구현하며, client-credentials / 서비스 계정 (service-account) 모드는 지원하지 않습니다.

1. 인증 없음 (개발용으로만 사용)

{
  "name": "local-tools",
  "connection_type": "stdio",
...

2. 정적 헤더 (공유 API 키)

curl -X POST http://localhost:8080/api/mcp/client \
  -H "Content-Type: application/json" \
  -d '{
...

3. 서버 수준 OAuth (관리자가 1회 승인)

관리자는 설정 중에 한 번 인증합니다. 이후 해당 MCP 서버로 전송되는 모든 요청은 호출자가 누구인지와 관계없이 저장된 동일한 토큰을 사용합니다.

curl -X POST http://localhost:8080/api/mcp/client \
  -H "Content-Type: application/json" \
  -d '{
...

oauth_config 객체는 client_id, client_secret, authorize_url, token_url, scopes 또는 동적 클라이언트 등록 (Dynamic Client Registration)을 위한 registration_url / server_url을 허용합니다. 관리자가 인증 단계를 완료한 후, POST /api/mcp/client/{id}/complete-oauth를 호출하여 마무리합니다.

4. 사용자별 OAuth (각 사용자가 직접 인증)

각 최종 사용자(end-user)가 자신의 계정으로 연결해야 하는 경우 auth_type: "per_user_oauth"를 사용합니다. Bifrost는 (identity, mcp_client) 쌍당 하나의 OAuth 토큰을 저장하고 이후 호출 시 이를 재사용합니다. Identity(신원)는 가상 키(virtual key), 로그인된 SSO 사용자 또는 x-bf-mcp-session-id를 통해 제공되어야 합니다.

5. 사용자별 헤더 (레거시 / 사용자 정의 사용자별 키)

curl -X POST http://localhost:8080/api/mcp/client \
  -H "Content-Type: application/json" \
  -d '{
...

Identity(신원)의 중요성: auth_type: "oauth" 또는 auth_type: "headers"를 사용하는 경우, 모든 호출자는 동일한 업스트림 자격 증명 (credential)을 공유합니다. Bifrost는 MCP 요청에 사용자별 신원을 첨부하지 않습니다. 업스트림에서 정확히 누가 작업을 수행했는지 파악하려면 per_user_oauth 또는 per_user_headers를 사용하십시오.

💻 런타임 도구 액세스 제어 (Virtual Keys)

RBAC는 에이전트가 런타임(runtime)에 어떤 MCP 도구를 호출할 수 있는지를 제어하지 않습니다. 이는 **가상 키 (virtual keys)**와 세 단계로 중첩된 도구 필터링 계층에 의해 제어됩니다:

1. 클라이언트 설정 (Client config) — 각 MCP 클라이언트의 tools_to_execute (기본값)
2. 요청 헤더 (Request headers) — 요청당 x-bf-mcp-include-clients 및 x-bf-mcp-include-tools 적용
3. 가상 키 설정 (Virtual key config) — mcp_configs 배열 (요청 헤더보다 우선순위가 높음)

기본 거부 (Deny-by-default)

이는 설정 항목이 아닌 내장된 동작입니다: mcp_configs가 없는 가상 키는 MCP 도구를 전혀 할당받지 못하며, mcp_configs에 나열되지 않은 클라이언트는 암시적으로 차단됩니다.

가상 키 설정 (Virtual key configuration)

curl -X POST http://localhost:8080/api/governance/virtual-keys \
  -H "Content-Type: application/json" \
  -d '{
...

이것은 RBAC 권한 문자열이 아니라, 서로 다른 가상 키에 서로 다른 mcp_configs를 부여함으로써 "백엔드 개발자는 스테이징(staging) API에는 접근할 수 있지만 운영(production) 데이터베이스에는 접근할 수 없다"와 같은 패턴을 강제하는 지점입니다.

요청별 범위 축소 (Per-request narrowing)

가상 키의 허용 목록(allowlist) 내에서 일회성 제한을 적용하려면 다음과 같이 합니다:

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer vk_new_dev" \
  -H "x-bf-mcp-include-tools: staging_database-query" \
...

참고: 가상 키에 mcp_configs가 설정되어 있으면, x-bf-mcp-include-tools가 자동으로 생성되며 수동으로 전송된 헤더를 덮어씁니다.

Bifrost는 SQL을 파싱하거나 쿼리 수준에서 DELETE / DROP과 같은 작업을 차단하지 않습니다. 특정 도구 이름만 허용하는 방식으로 액세스를 제한하십시오 (예: execute 도구 대신 읽기 전용인 query 도구 사용).

🔎 RBAC — 관리자 액세스

Bifrost는 MCP 게이트웨이 설정을 편집하고, 로그를 읽고, 가드레일(guardrails)을 구성하며, 가상 키를 관리하는 등의 작업을 수행하는 **관리 인터페이스 (administrative surface)**를 위한 역할 기반 액세스 제어 (RBAC, Role-Based Access Control)를 제공합니다. RBAC는 MCP 도구를 호출하는 에이전트를 위한 런타임 권한 부여(authorization)가 아닙니다.

권한은 mcp:tool:invoke와 같은 권한 문자열(permission strings)이 아니라, 리소스 × 작업 (Resource × Operation) 쌍입니다.

시스템 역할 (System roles)

또한 사용자 정의 역할(custom roles)을 생성할 수도 있습니다 (예: AuditLogs:View 및 Logs:View 권한만 가진 Auditor 역할).

보호된 리소스 (Protected resources) 포함 항목:

Logs, VirtualKeys, MCPGateway, MCPToolGroups, MCPLogs, GuardrailsConfig, AuditLogs, Cluster 등이 포함됩니다.

작업 (Operations) 포함 항목:

View, Create, Update, Delete, Download, Reveal 및 추론 작업 (inference operations)이 포함됩니다.

예시: 사용자 정의 Auditor 역할은 AuditLogs:View 및 AuditLogs:Download 권한을 부여할 수 있지만, MCPGateway:Update 권한은 부여하지 않을 수 있습니다. 이는 대시보드에서 게이트웨이를 *설정(configure)*할 수 있는 사람을 제어하는 것이지, 에이전트가 런타임에 어떤 도구를 실행하는지를 제어하는 것이 아닙니다.

역할과 권한은 대시보드의 Governance → Roles & Permissions 메뉴 또는 /api/roles 엔드포인트를 통해 관리됩니다:

curl -X GET http://localhost:8080/api/roles/{role_id}/permissions \
  -H "Authorization: Bearer <admin_token>"

🖥️ 사용자 프로비저닝 (User Provisioning) 및 역할 매핑 (role mapping)

role_sync 설정 블록은 존재하지 않습니다. 역할 할당은 Okta, Microsoft Entra 등을 지원하는 **OIDC를 통한 사용자 프로비저닝 (User Provisioning over OIDC)**을 통해 이루어집니다.

SSO가 구성된 경우:

• 사용자는 OAuth 2.0 / OIDC (Authorization Code + PKCE)를 통해 기업 자격 증명으로 로그인합니다.
• IdP 그룹 (IdP groups), 앱 역할 (app roles) 또는 **사용자 정의 클레임 (custom claims)**에서 Bifrost 역할(Admin, Developer, Viewer 또는 사용자 정의 역할)로 역할이 매핑됩니다.
• 역할 및 팀 할당은 매 세션마다 동기화됩니다.
• 백그라운드 조정(reconciliation)은 24시간마다 실행되며, OIDC 세션 갱신(refresh) 확인은 15분마다 실행됩니다.
• 비활성 또는 프로비저닝 해제된 사용자는 로컬에서 제거됩니다 (인바운드 SCIM 2.0을 통한 제거 포함).

설정은 config.json 내의 scim_config 아래에 위치합니다. 제공자별 설정 가이드는 User Provisioning docs를 참조하세요.

📋 감사 로그 (Audit logs)

Bifrost의 감사 로그 (Audit logs)는 누가, 무엇을, 언제 변경했는지, 그리고 어떤 리소스가 영향을 받았는지와 같은 **관리 활동 (administrative activity)**을 기록합니다. 이 로그는 log_level / capture / export_to 블록을 사용하지 않습니다.

실제 구성 형태:

{
  "audit_logs": {
    "disabled": false,
...

주요 기능:

• 서명된 이벤트 (Signed events) — 검증을 위한 HMAC 키를 구성합니다.
• 대시보드 검토 (Dashboard review) — 검색 텍스트, 작업 (action), 결과 (outcome) 및 날짜 범위별로 필터링합니다.
• 내보내기 (Export) — JSON, JSON Lines 또는 Syslog 형식을 지원합니다 (AuditLogs:Download 권한 필요).
• 보관 (Retention) — retention_days를 통해 데이터베이스 보관 기간을 제어합니다.
• 객체 스토리지 아카이빙 (Object storage archival) — 장기적인 컴플라이언스 (compliance) 유지를 위해 S3/GCS로 선택적 미러링을 수행합니다.

대시보드의 Governance → Audit Logs에서 감사 항목을 확인할 수 있습니다.

✅ 구현 베스트 프랙티스 (Implementation best practices)

1. 기본 거부 (deny-by-default) 원칙 준수

"policy": "default_deny" 설정을 찾지 마세요. 그런 설정은 존재하지 않습니다. 대신 다음을 수행하세요:

• 각 팀 또는 환경에 대해 명시적인 mcp_configs를 포함하는 가상 키 (virtual keys)를 생성합니다.
• 클라이언트 수준의 tools_to_execute를 필요한 최소한으로 설정합니다.
• 로컬 개발에 사용되는 키에는 운영 (production) 데이터베이스 도구 사용을 비활성화합니다.

2. 인간 참여 (human-in-the-loop)를 기본값으로 유지

명시적으로 검토한 도구에 대해서만 에이전트 모드 (Agent Mode) 자동 실행을 활성화하세요. 기본 흐름인 '채팅 → 검토 → /v1/mcp/tool/execute'가 가장 강력한 안전망입니다.

3. 런타임 액세스 (runtime access)와 관리 액세스 (admin access) 분리

• 런타임 (Runtime) (에이전트가 할 수 있는 일): 가상 키 (virtual keys) + mcp_configs + 요청 헤더 (request headers)
• 관리 (Administration) (누가 구성을 변경할 수 있는지): RBAC + SSO

4. 환경 범위가 지정된 가상 키 (environment-scoped virtual keys) 사용

{
  "name": "production-readonly",
  "mcp_configs": [
...

{
  "name": "staging-full",
  "mcp_configs": [
...

5. 감사 로깅 (audit logging) 조기 구성

HMAC 서명을 활성화하고, retention_days를 아카이빙 기간보다 충분히 길게 설정하며, 컴플라이언스 (compliance)를 위해 선택적으로 객체 스토리지 (object storage)로 미러링하세요.

6. 정기적인 액세스 검토 (access reviews) 수행

다음 질문에 답하기 위해 분기별 검토 (quarterly reviews)를 일정에 따라 수행하세요:

• 어떤 가상 키 (virtual keys)가 프로덕션 (production) MCP 클라이언트에 대한 액세스 권한을 부여하고 있는가?
• 엔터프라이즈 (Enterprise) 내에서 누가 관리자 (Admin) 또는 개발자 (Developer) RBAC 역할을 보유하고 있는가?
• 과도한 권한을 가진 가상 키 (virtual keys)나 휴면 상태인 SSO 계정이 있는가?