5분 만에 모든 MCP 서버 앞에 보안 게이트웨이 구축하기

AI 에이전트 (AI agent)를 출시하고 있다면, 파일 시스템 (filesystem), GitHub, 웹 검색 (web search), 결제 (payments) 등을 위해 하나 이상의 MCP 서버에 연결했을 것입니다. 하지만 여기 불편한 진실이 있습니다. 오늘날 대부분의 MCP 설정에는 인증 (auth)도, 속도 제한 (rate limit)도, 감사 로그 (audit log)도, 지출 제어 (spending control)도 없습니다.

당신의 MCP URL에 접속할 수 있는 사람이라면 누구든 지갑을 털어가거나, 파일을 유출하거나, 유료 API 비용을 폭증시킬 수 있습니다. 방화벽도 없습니다. if amount > $5, ask me first (금액이 5달러를 초과하면 먼저 물어보기) 같은 기능도 없습니다. 아무것도 없습니다.

저는 방금 에이전트와 모든 MCP 서버 사이에 위치하는 작은 오픈 소스 (open-source) 게이트웨이인 mcp-guard를 출시했습니다. pip install 한 번과 설정 파일 하나만 있으면 바로 유용하게 사용할 수 있습니다.

pip install bonanza-mcp-guard
mcp-guard scan     # 기존 설정의 취약점 확인
mcp-guard serve    # 30초 만에 어떤 MCP 서버든 래핑 (wrap)

이 도구가 무엇을 하는지, 왜 만들었는지, 그리고 어떻게 지금 바로 당신의 스택 (stack)에 연결할 수 있는지 설명하겠습니다.

제가 계속 마주쳤던 문제

유료 API (Stripe, OpenAI, Anthropic, Twilio, 날씨 API)와 통신하는 에이전트를 출시하기 시작했을 때, 저는 MCP가 기본적으로 제공하지 않는 다섯 가지 기능을 원했습니다:

1. 인증 (Authentication) — 누가 이것을 호출하고 있는가? 에이전트가 주장하는 본인이 맞는가?
2. 속도 제한 (Rate limits) — 에이전트별, 도구 (tool)별, 분당 제한. 하나의 오작동하는 에이전트가 예산을 폭발시키는 것을 방지.
3. 지출 한도 (Spend caps) — $50 가치의 wallet_pay는 항상 저의 승인을 필요로 해야 합니다.
4. 감사 로그 (Audit log) — 모든 도구 호출에 대한 JSONL 기록: 누가, 무엇을, 언제, 얼마만큼, 그 다음에 무슨 일이 일어났는지.
5. 승인 대기열 (Approval queue) — 비싸거나 민감한 작업이 들어오면 대기시킵니다. 저에게 Slack 메시지를 보내고, 제가 휴대폰에서 승인하거나 거부할 수 있게 합니다.

MCP 자체는 훌륭합니다. 깔끔한 프로토콜 (protocol)입니다. 프로토콜 명세 (protocol spec)로서 보안 계층 (security layer)이 되려고 하지 않는 것은 올바른 결정입니다. 하지만 누군가는 보안 계층을 구축해야 합니다.

그래서 제가 만들었습니다.

mcp-guard가 하는 일

mcp-guard는 **투명 프록시 (transparent proxy)**입니다. 어떤 MCP 서버 (stdio 또는 HTTP) 앞에도 배치할 수 있으며, 다음을 강제합니다:

• 🔐 4가지 인증 모드 (auth modes) — 없음 (none), API 키 (timing-safe SHA-256), JWT, 또는 PKCE + Device flow를 포함한 완전한 OAuth2
• 🚦 속도 제한 (Rate limits) — 30 req/min, 에이전트별 또는 전역적으로 설정 가능
• 💸 지출 한도 (Spend caps) — require_approval_above: 5.0 → 도구 호출 (tool calls) 비용이 $5 이상이면 승인 대기열 (approval queue)에 머무름
• 🧾 감사 로그 (Audit logs) — JSONL 형식, 호출당 한 줄씩 기록, Splunk/Datadog 등에 즉시 활용 가능
• ✋ 승인 대기열 (Approval queue) — SQLite 기반. 에이전트는 approval_id와 함께 -32004 approval_pending 응답을 받습니다. 사용자가 mcp-guard approvals approve <id>를 실행하면 끝입니다.
• 🚫 도구 허용/차단 목록 (Tool allowlist/denylist) — 서버별로 deny: ["filesystem.delete", "wallet_pay"] 설정 가능
• 📊 Prometheus 메트릭 (Prometheus metrics) — HTTP 게이트웨이의 GET /metrics를 통해 제공, Grafana에 바로 적용 가능
• 🐳 Docker 이미지 (Docker image) — docker run mcp-guard serve --config /etc/mcp-guard.yaml
• 🔀 멀티 서버 라우팅 (Multi-server routing) — 하나의 게이트웨이로 여러 백엔드 연결. wallet_pay → bonanza, read_file → filesystem, 기본값 → search로 라우팅.

이 모든 기능은 필수 의존성(dependencies)이 전혀 없으며 (YAML 설정을 원하는 경우에만 pyyaml 필요), 약 2,900줄의 Python 코드로 이루어져 있습니다. 오후 한나절이면 전체 코드베이스를 다 읽을 수 있습니다.

5분 설정 방법

1. 설치

pip install "bonanza-mcp-guard[yaml]"

2. 기존 설정 스캔

mcp-guard scan

이 명령은 Claude Desktop 설정(~/Library/Application Support/Claude/), Cursor 설정(~/.cursor/mcp.json), 그리고 모든 로컬 mcp.json 파일들을 탐색합니다. 다음 사항들을 표시합니다:

• 🔴 인증이 없는 MCP 서버
• 🔴 직접적인 stdio 명령 (래퍼(wrapper) 없음, 정책 없음, 로그 없음)
• 🟡 명확한 인증이 없는 원격 URL

이 명령은 무엇을 수정하지는 않으며, 단지 보안 취약점(holes)을 보여줄 뿐입니다.

3. MCP 서버 래핑 (Wrap)

설정 파일을 생성합니다:

# mcp-guard.yaml
auth:
  mode: api_key
...

실행합니다:

export AGENT_API_KEY=$(openssl rand -hex 32)
mcp-guard serve --config mcp-guard.yaml

이제 에이전트는 순수 MCP 서버 대신 mcp-guard를 호출합니다. 모든 기능은 동일하게 작동하지만, 모든 호출은 이제 인증되고, 속도가 제한되며, 감사 로그가 남고, (비용이 많이 드는 경우) 승인을 위해 대기하게 됩니다.

4. 승인 처리 (Handle approvals)

에이전트가 $amount: 10과 함께 wallet_pay를 호출하면 다음과 같은 응답을 받습니다:

{
  "jsonrpc": "2.0",
  "id": 42,
...

이 내용은 감사 로그(audit log), Slack, 또는 휴대폰을 통해 확인할 수 있습니다. 다음 명령어를 실행하세요:

mcp-guard approvals list
mcp-guard approvals approve appr_7f3a9c

에이전트가 재시도하면 호출이 통과되고, 감사 로그에 귀하의 결정이 기록됩니다.

상태는 지속적 (persistent) (SQLite)이므로, 재시작 후에도 승인 내역이 유지됩니다. 또한 require_approval_above는 **도구별, 금액별 (per-tool, per-amount)**로 적용됩니다. 즉, $4.99는 통과되지만 $5.01은 대기하게 됩니다.

5. CI에 연결하기 (Wire it up to your CI)

mcp-guard는 모든 PR(Pull Request)에서 MCP 설정을 스캔하는 GitHub Action을 함께 제공합니다:

# .github/workflows/mcp-scan.yml
name: mcp-scan
on: [pull_request]
...

저는 .mcp.json 피스처(fixture)를 사용하여 mcp-guard 자체에서 이를 테스트했습니다. 6개의 경고가 포함된 실시간 댓글을 PR에 게시한 후, 깨끗하게 머지(merge)되었습니다. 실제 출력 결과는 test PR에서 확인할 수 있습니다.

이를 구축하며 배운 점

몇 가지 놀라웠던 점들이 있습니다:

1. 승인 대기열(approval queue)이 핵심 기능(killer feature)입니다. 저는 인증(auth)과 속도 제한(rate limiting)이 주요 특징이 될 것이라고 예상했습니다. 하지만 아니었습니다. 승인 대기열을 출시하자마자 테스트한 모든 사람이 "오, 바로 이게 제가 필요했던 거예요"라고 말했습니다. 에이전트가 돈을 쓰려고 할 때, 인간이 개입(human in the loop)해야 합니다. 그것이 바로 이 제품의 핵심 가치(pitch)가 되었습니다.

2. JSON-RPC 에러 코드가 API 접점(API surface)이 됩니다. -32004 approval_pending은 이제 도구와 대시보드가 기반으로 삼을 수 있는 안정적인 규약(contract)이 되었습니다. 확장 코드(extension codes)를 신중하게 선택하세요. 그것들은 영구적입니다.

3. JWT 라이브러리 없이 PKCE를 구현하는 것이 생각보다 쉽습니다. mcp-guard의 OAuth2 프로바이더는 PKCE S256을 사용하는 HMAC-SHA256 서명 액세스 토큰을 처리합니다. JWT 의존성 없이 약 150줄의 코드로 RFC를 준수하며 구현되었습니다.

4. Docker는 stdio MCP를 위한 비밀 병기입니다. HTTP 전송 방식(mcp-guard serve-http)도 훌륭하지만, 진정한 핵심은 stdio 서버를 Docker로 감싸고 이를 HTTP로 노출한 뒤, 그 앞에 실제 인증 계층을 배치하는 것입니다. 이렇게 하면 세상의 모든 MCP 서버를 브라우저 탭에서 접근할 수 있게 됩니다.

구현되지 않은 기능

현재 누락된 기능들에 대해 솔직하게 말씀드리고자 합니다:

• 에이전트별 도구 허용 목록 (per-agent tool allowlist) 미지원. 현재는 서버별로 전역적인 도구 거부가 가능합니다. 에이전트별 허용 목록은 로드맵(이슈 트래커)에 포함되어 있습니다.
• 대시보드 없음. 감사 로그(Audit log)는 JSONL 형식입니다. Datadog 등으로 파이프라이닝하기에는 좋지만, 사람이 직접 보기에는 불편합니다.
• OAuth2 상태가 인메모리 (in-memory) 방식임. 다중 복제본 배포(Multi-replica deployments)를 위해서는 데이터베이스 백엔드(Redis 또는 SQLite)가 필요합니다.

만약 이러한 기능들 때문에 사용이 어렵다면 이슈를 생성해 주세요. 실제 버그가 보고되면 빠르게 수정하여 배포합니다.

사용해 보기

• GitHub: https://github.com/c6zks4gssn-droid/mcp-guard
• PyPI: pip install bonanza-mcp-guard
• Docker: docker pull ghcr.io/c6zks4gssn-droid/mcp-guard:v0.1.4
• Issues: https://github.com/c6zks4gssn-droid/mcp-guard/issues

MCP 서버와 통신하는 에이전트를 배포하고 있다면, 딱 5분만 투자해 보세요. 설정을 살펴보고, 서버 하나를 감싸고, 비용이 많이 드는 도구 호출(tool call)을 한 번 보내보세요. 이것이 왜 필요한지 즉각적으로 이해되지 않는다면, 여러분의 시간을 돌려드려도 좋습니다.

자기소개: 저는 Bonanza Labs를 운영하고 있습니다. 저희는 에이전트 경제(agent economy)를 위한 보안 및 툴링을 배포합니다. mcp-guard는 저희가 유지 관리하는 수십 개의 오픈 소스 패키지 중 하나입니다. 저희가 다음에 무엇을 작업할지 알고 싶다면 X (@myopenclaw)에서 저를 팔로우해 주세요.