Firewall: MCP Servers

Model Context Protocol(MCP)은 에이전트가 외부 서버에서 호스팅되는 툴을 호출할 수 있게 합니다. 그것은 똑같이 강력하고 위험합니다: 에이전트가 연결하는 모든 MCP 서버는 아무도 검토하지 않은 새로운 툴, 자격 증명, 그리고 네트워크 도달 범위의 집합입니다. Firewall의 MCP 게이트웨이는 그 모든 것 앞에 단일 감사 초크 포인트를 둡니다. 각 MCP 서버를 한 번 등록하면; 게이트웨이는 그 툴을 하나의 연결 아래에서 에이전트에게 노출하고, 모든 tools/call을 실제 서버에 도달하기 전에 firewall 엔진을 통해 실행합니다.

1. MCP 거버넌스가 주는 것

하나의 게이트웨이, 모든 서버. 에이전트는 하나의 엔드포인트에 연결합니다. 게이트웨이는 도달 가능한 모든 등록된 서버의 툴을 <server>.<tool>로 네임스페이스 처리하여 집계하므로, github.create_issue와 shell.exec가 단일 MCP 연결 아래 나란히 나타납니다.
모든 호출에 정책. 각 tools/call은 먼저 당신의 정책에 의해 평가됩니다. 차단된 호출은 전송 실패가 아니라 툴 오류(firewall deny: …)로 모델에게 돌아오므로, 에이전트가 크래시하는 대신 반응할 수 있습니다. sanitize는 전달 전에 인자를 재작성합니다; pending_approval은 호출을 보류합니다.
SSRF 보호. 원격 엔드포인트는 게이트웨이의 SSRF 정책에 대해 검증됩니다 — 인트라넷 범위와 클라우드 메타데이터 주소가 차단되며, 리다이렉트를 포함한 모든 홉에서 해석된 다이얼 IP가 DNS 리바인딩을 무력화하기 위해 다시 검사됩니다.
암호화된 자격 증명. 서버 인증 시크릿은 저장 시 암호화되고 읽기 시 마스킹됩니다. 게이트웨이는 디스패치 시점에 그것들을 주입합니다; 그것들은 결코 모델이나 클라이언트에 도달하지 않습니다.

2. 두 종류의 서버

종류	`endpoint`	동작
BYO (bring-your-own)	streamable-HTTP URL	게이트웨이가 `tools/call`을 당신의 원격 MCP 서버로 프록시합니다.
Bundled	비어 있음	OrcaRouter의 인프로세스 MCP 서버. 보이고 통제 가능하도록 등록됨; 별도로 프로빙 불가.

3. 서버 등록하기

서버 레코드는 다음을 담습니다:

필드	참고
`name`	비즈니스 키, 워크스페이스당 고유, ≤ 128자. `.` 없음 — 그것은 `<server>.<tool>` 네임스페이스 구분자입니다.
`endpoint`	MCP 서버 URL(≤ 512자). 번들 서버는 비어 있음.
`auth_mode`	`none`(기본값), `bearer`, `oauth`, 또는 `basic`.
`auth_json`	모드별 자격 증명(아래 참조). `auth_mode`가 `none`이 아닐 때마다 필수.
`enabled`	기본값 `true`. 비활성화된 서버는 게이트웨이에서 전적으로 생략됩니다.
`status`	도달 가능성 — `ok`(기본값), `degraded`, 또는 `down`. 프로빙에 의해 설정됨.

모드별 자격 증명 형태:

// bearer
{ "token": "ghp_…" }
// oauth
{ "client_id": "…", "client_secret": "…", "token_url": "…" }
// basic
{ "username": "…", "password": "…" }
// none
""

등록 요청은 다음과 같습니다:

curl https://api.orcarouter.ai/api/workspace/firewall/mcp_servers \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "github",
    "endpoint": "https://api.githubcopilot.com/mcp",
    "auth_mode": "bearer",
    "auth_json": "{\"token\":\"ghp_x\"}",
    "enabled": true
  }'

동일한 워크스페이스의 중복 이름은 HTTP 409를 반환합니다(다른 워크스페이스의 동일한 이름은 괜찮습니다).

시크릿은 결코 평문으로 저장되지 않습니다. auth_json은 워크스페이스 시크릿 키로 저장 시 암호화됩니다. 그 키가 구성되지 않았으면, 자격 증명을 암호화되지 않은 채 영속화하기보다 쓰기가 거부됩니다. 읽기 시 시크릿과 엔드포인트는 마스킹됩니다; 저장된 값을 유지하려면 업데이트 시 마스크를 그대로 돌려보내세요. 두 자격 증명 인증 모드 간 전환은 새로운 auth_json을 요구합니다(암호문은 그 모드에 형태가 묶여 있습니다).

4. Probe — 그 툴을 발견하기

서버의 툴에 대해 규칙을 작성하려면 먼저 그 이름을 알아야 합니다. 서버를 Probe하세요:

curl -X POST \
  https://api.orcarouter.ai/api/workspace/firewall/mcp_servers/42/probe \
  -H "Authorization: Bearer sk-orca-..."

게이트웨이는 엔드포인트에 대해 MCP initialize + tools/list를 실행하고(복호화된 자격 증명을 사용, 10s로 제한), 도달 가능성 status와 타임스탬프를 기록하며, 광고된 툴을 그 입력 스키마와 함께 반환합니다:

{
  "status": "ok",
  "last_checked_at": 1700000000,
  "tools": [
    { "name": "create_issue", "description": "…", "input_schema": { } }
  ]
}

이제 github.create_issue가 무엇을 받아들이는지 정확히 알고 tool_name_glob: github.* 같은 규칙을 작성할 수 있습니다. 번들(빈 엔드포인트) 서버는 프로빙할 수 없으며 400을 반환합니다.

5. 수명 주기 및 강제

활성화 vs. 비활성화. 비활성화된 서버는 런타임 레지스트리에서 제거됩니다 — 그 툴은 게이트웨이에서 사라지고 그 자격 증명은 결코 복호화되지 않습니다. 그것이 오프 스위치입니다.
도달 가능성. status(ok / degraded / down)는 마지막 프로브를 반영합니다; 도달 불가능한 서버는 게이트웨이가 툴 세트를 빌드할 때 건너뜁니다.
호출별 판정. 디스패치 시 엔진은 인자와 함께 특정 <server>.<tool> 호출에 대한 판정을 반환합니다:
- allow / audit → 전달됨(감사 로깅, 여전히 허용).
- sanitize → 재작성된 인자와 함께 전달됨.
- deny / pending_approval / 알 수 없는 모든 것 → 툴 오류로 차단됨. (통합 게이트웨이를 통하면, held 호출은 승인 id를 엮는 대신 영구 오류로 표면화됩니다 — 승인 핸드셰이크가 필요할 때는 evaluate 훅을 사용하세요.)
삭제는 소프트 삭제입니다; 이름 슬롯이 즉시 해제되므로 동일한 이름으로 재등록할 수 있습니다.

모든 변경은 게이트웨이의 워크스페이스별 툴 캐시를 즉시 무효화하므로, 새로 등록되거나, 비활성화되거나, 다시 프로빙된 서버는 캐시 TTL 후가 아니라 다음 연결에서 반영됩니다.

6. 클라이언트 연결하기

임의의 MCP 클라이언트를 firewall-gateway-scoped 토큰과 함께 게이트웨이 엔드포인트로 가리킵니다:

https://api.orcarouter.ai/api/v1/firewall/mcp

게이트웨이는 streamable HTTP를 말하고(POST 메시지, SSE 스트림용 GET, 세션 종료용 DELETE) 자신을 orcarouter-firewall-gateway로 식별합니다. 그것은 활성화되고 도달 가능한 모든 서버의 툴을 <server>.<tool> 네임스페이스 아래 광고하며, 각 툴의 입력 스키마를 그대로 다시 노출합니다. firewall-gateway 스코프가 없는 토큰은 403을 받습니다 — 이를 위해 전용 게이트웨이 토큰을 발급하세요.

API 레퍼런스

콘솔 (워크스페이스 범위, RBAC)

메서드 및 경로	역할	목적
`GET /api/workspace/firewall/mcp_servers`	Member	서버 목록(시크릿 마스킹, 엔드포인트 마스킹).
`GET /api/workspace/firewall/mcp_servers/:id`	Member	단일 서버, 마스킹됨.
`POST /api/workspace/firewall/mcp_servers`	Developer+	서버 등록(중복 이름에 409).
`PUT /api/workspace/firewall/mcp_servers`	Developer+	서버 업데이트(본문에 id).
`DELETE /api/workspace/firewall/mcp_servers/:id`	Developer+	소프트 삭제; 이름 해제.
`POST /api/workspace/firewall/mcp_servers/:id/probe`	Developer+	도달 가능성 프로브 + 툴 발견.

게이트웨이 (firewall-gateway-scoped 토큰)

메서드 및 경로	목적
`ANY /api/v1/firewall/mcp`	통합 MCP 게이트웨이 디스패치 엔드포인트.
`GET /api/v1/firewall/mcp_servers`	SDK 프록시를 위한 런타임 레지스트리(복호화된 인증, 활성화된 서버만).
`POST /api/v1/firewall/evaluate`	직접 디스패치하기 전에 단일 `tools/call` 평가.

FAQ

애초에 왜 MCP를 OrcaRouter를 통해 라우팅하나요?

모든 툴 호출을 보는 한 곳이 있도록. 게이트웨이가 없으면 각 에이전트가 각 MCP 서버에 직접 연결합니다 — 공유 정책 없음, 감사 추적 없음, SSRF 보호 없음, 그리고 에이전트 구성 전반에 흩어진 자격 증명. 게이트웨이는 그 모든 것을 중앙화합니다: 하나의 연결, 하나의 정책, 하나의 감사 로그, 디스패치 시점에 주입되는 암호화된 시크릿.

차단된 MCP 호출이 돌아오면 어떻게 되나요?

모델은 그것을 툴 오류(firewall deny: <reason>)로 받습니다 — 실패하는 어떤 툴에서든 받을 것과 동일한 형태. 그것은 에이전트가 적응하게 합니다 — 다른 접근을 시도, 사용자에게 질문, 또는 중단 — 전송 크래시로 취급하는 대신.

동일한 툴을 서버별로 다르게 통제할 수 있나요?

예 — 그것이 <server>.<tool> 네임스페이스의 목적입니다. tool_name_glob: trusted.* 규칙은 allow할 수 있는 반면 community.*는 audit되거나 pending_approval될 수 있습니다. 더 세밀한 범위 지정을 위해 skill 이름 glob과 결합하세요.

게이트웨이는 SSRF로부터 보호하나요?

예. 엔드포인트 URL과 그 해석된 다이얼 IP는 등록 시와 모든 디스패치 홉에서 SSRF 정책에 대해 검증됩니다 — 인트라넷 범위와 클라우드 메타데이터 주소가 거부되며, 해석된 IP가 DNS 리바인딩을 무력화하기 위해 다시 검사됩니다. 툴이 어디에 도달할 수 있는지를 통제하려면 egress 규칙과 짝지으세요.

MCP 서버 보안 (제로 트러스트)

제로 트러스트 자세 아래에서 MCP 서버를 연결, 인증, 통제하세요.

MCP 신뢰 체크리스트

서드파티 MCP 서버를 신뢰하기 전에 확인할 것.

​1. MCP 거버넌스가 주는 것

​2. 두 종류의 서버

​3. 서버 등록하기

​4. Probe — 그 툴을 발견하기

​5. 수명 주기 및 강제

​6. 클라이언트 연결하기

​API 레퍼런스

​콘솔 (워크스페이스 범위, RBAC)

​게이트웨이 (firewall-gateway-scoped 토큰)

​FAQ

​더 보기