mcp-policy-gateway

정책 우선(policy-first) MCP 서버 참조 구현입니다. 에이전트에게 유용한 도구를 제공하면서도, 모델이 권한 부여를 결정하거나, 테넌트 경계를 넘거나, 직접적인 PII를 유출하거나, 고영향 변경을 스스로 실행하지 못하도록 하는 방법을 보여줍니다.

이는 포트폴리오/참조 구현입니다. 모든 레코드는 합성 데이터이며, 프로덕션 소프트웨어가 아니며 은행, 결제 처리자, 고객 시스템과의 통합을 주장하지 않습니다.

왜 존재하는가

일반적인 MCP 데모는 원시 API를 모델에 노출하고 성공적인 도구 호출을 보안 모델로 취급합니다. 이 프로젝트는 반대 입장을 취합니다:

• 정책은 결정적입니다. 모델은 스스로를 승인할 수 없습니다.

• 테넌트 경계는 서버 측에서 강제됩니다. 도구 인자가 테넌트를 변경할 수 없습니다.

• 도구 출력은 최소화됩니다. 계정 요약은 의도적으로 소유자 이름과 이메일을 제외합니다.

• 고영향 작업은 승인 게이트에서 중단됩니다. 동결 요청은 상태 변경을 생성하지 않습니다.

• 모든 결정은 감사 가능합니다. 허용, 거부, 승인 필요 결과는 구조화된 감사 이벤트를 생성합니다.

• 변경 요청에는 사유와 멱등성 키가 필요합니다.

Related MCP server: scopeguard-mcp

아키텍처

MCP client / agent
       │ tool call
       ▼
FastMCP stdio adapter
       │ verified principal (demo fixture here)
       ▼
GatewayService ──► PolicyEngine ──► allow / deny / require approval
       │                 │
       ▼                 ▼
synthetic domain data   structured audit event

프로덕션 배포에서는 주체(principal)가 모델 컨텍스트 외부의 검증된 ID/세션에서 파생되어야 합니다. tenant_id, 역할, 범위를 도구 인자나 모델 출력에서 절대 수락하지 마십시오.

도구

빠른 시작

Python 3.11+ 필요.

python -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/pytest
.venv/bin/ruff check .

MCP stdio 서버로 실행:

.venv/bin/mcp-policy-gateway

어댑터는 로컬 탐색을 위해 의도적으로 고정된 데모 주체를 사용합니다. 실제 ID 전파는 여기서 가짜로 구현하지 않고 프로덕션 통합 고려 사항으로 의도적으로 문서화합니다.

입증된 남용 통제

테스트는 게이트웨이가 다음을 증명합니다:

1. tenant_red의 에이전트가 tenant_blue 데이터를 읽으려는 시도를 거부합니다;

2. 필수 범위가 없는 도구 호출을 거부합니다;

3. 요약 도구를 통해 소유자 이름이나 이메일을 반환하지 않습니다;

4. 계정 상태를 변경하는 대신 require_approval을 반환합니다; 그리고

5. 사유나 멱등성 키가 누락된 상태 변경 요청을 거부합니다.

위협 모델 및 비목표

THREAT_MODEL.md를 참조하십시오. 설계는 의도적으로 좁습니다: MCP 도구 주변의 정책 경계를 보여주며, 완전한 ID 인프라, 지속적 감사 저장소, 비밀 관리, 또는 결제/원장 시스템을 다루지 않습니다.

인터뷰 워크스루

프로젝트를 간결하게 설명하는 방법:

저는 MCP 경계를 설계하여 모델이 안전하고 범위가 제한된 데이터에 대해 추론할 수 있지만, 접근을 결정하거나 고영향 작업을 실행할 수 없도록 했습니다. 권한 부여는 결정적이며, 테넌트 격리는 서버 측에서 강제되고, 도구 표면은 PII를 최소화하며, 민감한 변경은 감사 가능한 인간 승인 게이트에서 종료됩니다.

개발

.venv/bin/pytest
.venv/bin/ruff check .

CI는 푸시와 풀 리퀘스트 모두에서 두 검사를 실행합니다.

라이선스

MIT. LICENSE를 참조하십시오.