Molayo

© 2026 Molayo

GitHub요약2026. 05. 29. 11:49

FareedKhan-dev/production-grade-mcp-agentic-system

요약

단순한 데모를 넘어 실제 서비스 운영이 가능한 프로덕션급 MCP(Model Context Protocol) 에이전트 시스템의 참조 구현체입니다. 멀티테넌시, 인증, 속도 제한, 서킷 브레이커 등 기업 환경에 필수적인 12가지 핵심 구성 요소를 포함합니다.

핵심 포인트

  • 프로덕션 환경을 위한 MCP 서버 참조 구현 제공
  • 멀티테넌트, 인증, 관찰 가능성 등 엔터프라이즈 기능 포함
  • 4단계 에이전트 오케스트레이션(Planner-Retriever-Synthesizer-Critic) 구조
  • 다양한 데이터 레이어(Postgres, S3 등)를 단일 도구 인터페이스로 통합

멀티테넌트 (Multi-tenant) · 인증됨 (Authenticated) · 관찰 가능함 (Observable) · 속도 제한 (Rate-limited) · 캐싱됨 (Cached) · 서킷 브레이커 (Circuit-broken) · 거버넌스 적용 (Governed)

이 저장소는 모든 구성 요소를 처음부터 끝까지 살펴보고, 모든 코드 라인을 문맥에 맞춰 설명하는 긴 글의 블로그 포스트를 위한 동반 코드베이스입니다. 코드를 읽기 전에 아키텍처 이면의 "이유(why)"를 이해하고 싶다면 블로그부터 시작하세요.

대부분의 MCP 튜토리얼은 단순히 "hello world"를 반환하는 @tool 데코레이터로 끝납니다. 데모용으로는 괜찮습니다. 하지만 실제 서비스로 출시되는 것은 아닙니다.

이 저장소는 **프로덕션 환경에서 실행되도록 설계된 MCP 서버의 참조 구현 (reference implementation)**입니다: 멀티테넌트 (multi-tenant), 인증 (authenticated), 관찰 가능성 (observable), 속도 제한 (rate-limited), 캐싱 (cached), 서킷 브레이커 (circuit-broken), 그리고 거버넌스 (governed) 기능이 포함되어 있습니다. 이 시스템은 기업의 이기종 데이터 레이어 (Postgres, Elasticsearch, S3, vector DB)를 AI 에이전트에게 단일하고 안전한 도구 인터페이스로 노출하며, 이를 엔드 투 엔드로 사용하는 4개 에이전트 지원 코파일럿 (four-agent support copilot) (Planner → Retriever → Synthesizer → Critic)과 함께 제공됩니다.

코드베이스는 팀들이 이를 생략했을 때 새벽 3시 호출(pager)을 발생시키는 **12가지 구성 요소 (twelve components)**를 중심으로 의도적으로 구성되었습니다. 각 구성 요소는 자체 모듈에 존재하며 독립적으로 읽기, 교체 또는 확장이 가능합니다.

완전한 프로덕션급 시스템: 오른쪽에는 MCP 서버 디스패치 파이프라인 (MCP server dispatch pipeline), 왼쪽에는 4개 에이전트 오케스트레이터 (four-agent orchestrator), 상단에는 데이터 플레인 (data plane), 하단에는 관찰 가능성 (observability), 그리고 횡단 관심사 (crosscutting concerns)로서의 ID 및 거버넌스 (identity and governance)가 배치되어 있습니다.

#구성 요소 (Component)위치 (Lives in)제공 기능 (What it gives you)
1🚪 전송 및 세션 계층 (Transport & Session Layer)server.py로컬용 stdio, 원격용 스트리밍 가능 HTTP (Streamable HTTP), 수평 확장 (horizontal-scale)에 친화적인 세션
2🔐 인증 서버 (Authentication Server)auth/oauth.pyOAuth 2.1 + PKCE, 단기 수명 JWT (short-lived JWTs), JWKS 검증
3⚖️ 권한 부여 및 정책 엔진 (Authorization & Policy Engine)auth/policy.py도구 수준의 RBAC (역할 기반 액세스 제어), 테넌트 범위의 ABAC (속성 기반 액세스 제어), 기본 거부 (deny-by-default)
4📚 도구 레지스트리 및 탐색 (Tool Registry & Discovery)tools/registry.py동적 도구 세트 (Dynamic toolsets), .well-known 기능 메타데이터
5✅ 입력 검증 계층 (Input Validation Layer)validation/schemas.pyPydantic 스키마, 열거형 (enum) 제약 조건, 에이전트 적대적 입력 (agent-adversarial input)을 기본 위협 모델로 설정
6🔧 도구 실행 엔진 (Tool Execution Engine)tools/base.py3단계 계층 구조 (원자적 (atomic) / 조합형 (composed) / 워크플로 (workflow))
7🔄 서킷 브레이커 및 재시도 (Circuit Breaker & Retry)reliability/Closed → open → half-open, 적응형 타임아웃 예산 할당 (Adaptive Timeout Budget Allocation)
8🚦 속도 제한 및 할당량 (Rate Limiting & Quotas)ratelimit/limiter.pyRedis 토큰 버킷 (Lua-atomic), 테넌트별 및 도구별 제한
9⚡ 캐싱 계층 (Caching Layer)cache/manager.py2단계 캐싱 (L1 인프로세스, L2 Redis), 스탬피드 방지 (stampede prevention)
10🧱 구조화된 에러 프레임워크 (Structured Error Framework)errors/framework.pyretryable 및 hint 필드를 포함한 기계 판독 가능 에러
11🔭 관측성 스택 (Observability Stack)observability/OpenTelemetry 트레이스 (traces), Prometheus 메트릭 (metrics), 감사 로그 (audit logs)
12🛡️ 거버넌스 및 멀티 테넌시 (Governance & Multi-Tenancy)governance/테넌트 격리 (Tenant isolation), 승인 게이트 (approval gates), 아웃바운드 HTTP 허용 목록 (allowlisting)

아래의 각 다이어그램은 블로그의 해당 섹션으로 연결되며, 그곳에서 모든 코드 라인을 상세히 살펴볼 수 있습니다.

  • Docker & Docker Compose
  • Python 3.11+
  • Anthropic API 키 (에이전트 계층용)
git clone https://github.com/FareedKhan-dev/production-grade-mcp-agentic-system.git
cd production-grade-mcp-agentic-system
cp .env.example .env

.env 파일을 편집하여 최소한 다음 항목들을 설정하세요:

ANTHROPIC_API_KEY — 에이전트 계층용
ATLAS_AUTH_JWKS_URL

— 귀하의 OAuth 2.1 제공업체의 JWKS 엔드포인트 (또는 개발용으로 기본값 유지)

docker compose up -d

이를 통해 전체 로컬 환경이 실행됩니다:

서비스URL설명
🏛️ MCP Serverhttp://localhost:8080/mcp스트리밍 가능한 HTTP 엔드포인트
🔍 Discoveryhttp://localhost:8080/.well-known/mcp-server인증되지 않은 기능 메타데이터
📊 Metricshttp://localhost:8080/metricsPrometheus 스크레이프 (scrape) 대상
❤️ Healthhttp://localhost:8080/healthz라이브니스 프로브 (Liveness probe)
🔭 Jaegerhttp://localhost:16686분산 트레이싱 (Distributed tracing) UI
📈 Grafanahttp://localhost:3000메트릭 대시보드 (admin / admin)
🗄️ MinIO Consolehttp://localhost:9001S3 호환 스토리지 UI
pip install -e .
export ATLAS_MCP_URL=http://localhost:8080
export ATLAS_MCP_TOKEN=dev-token
...

네 가지 에이전트가 엔드-투-엔드 (end-to-end)로 실행되는 것을 볼 수 있으며, 최종 초안은 [S1][S2] 인용구와 함께 출력되고, 토큰 수, 도구 호출 (tool calls), 그리고 Jaeger와 연결되는 run_id를 포함한 전체 트레이스 (trace) 요약이 표시됩니다.

이를 MCP 호스트 설정에 추가하세요:

{
"mcpServers": {
"production-mcp": {
...

.
├── 📄 README.md
├── 🐳 docker-compose.yml # 전체 로컬 스택: 앱 + 데이터 + 관측성 (observability)
...
계층기술
언어Python 3.11+
웹 프레임워크Starlette + Uvicorn
MCP SDKmcp>=1.2.0
인증 (Auth)PyJWT + Authlib (OAuth 2.1 리소스 서버)
검증 (Validation)Pydantic v2 + Pydantic Settings
데이터베이스asyncpg (PostgreSQL 16, RLS 적용)
검색Elasticsearch 8 (async 클라이언트)
벡터 DBQdrant
객체 스토리지aioboto3 (MinIO / S3)
캐시 + 큐Redis 7 (redis[hiredis] )
신뢰성tenacity (재시도) + 커스텀 브레이커 (breaker) + 커스텀 ATBA
트레이싱 (Tracing)OpenTelemetry SDK + OTLP 익스포터 (exporter)
메트릭 (Metrics)prometheus_client
로깅 (Logging)structlog (JSON)
LLMAnthropic Messages API (Claude)

테스트 스위트는 세 가지 핵심 안전 속성 (safety properties)을 다루도록 의도적으로 좁게 설계되었습니다:

pip install -e ".[dev]"
pytest -v

— 상태 머신 전이 (state machine transitions), 재시도 가능 여부 vs 결정론적 오류 분류 (retryable vs deterministic error classification) test_circuit_breaker.py

— SERF 와이어 포맷 (wire format), 재시도 의미론 (retry semantics), MCP 레벨 오류 데이터 test_errors.py

— 기본 거부 (default-deny), 거부가 허용보다 우선 (deny-beats-allow), 글로브 매칭 (glob matching), PII 조건 차단 test_policy.py

실제 운영 환경(관리형 Postgres, 실제 OAuth 제공자, SIEM 통합, Kubernetes)에서 이를 실행하려면 docs/DEPLOYMENT.md를 참조하세요.

로컬 개발과 운영 환경 간의 주요 교체 사항:

로컬 (docker-compose)운영 (Production)
개발용 JWT 발급자 (Dev JWT issuer)WorkOS AuthKit / Auth0 / Keycloak
...
  • 📖 블로그 가이드 (Blog Walkthrough)
    — 운영 수준의 MCP 서버 구축 (Building a Production-Grade MCP Server) (권장 시작 지점) - 🏗️ docs/ARCHITECTURE.md

— 12가지 구성 요소 심층 분석 (The 12 components in depth) - 🤖 docs/AGENT_SYSTEM.md

— 멀티 에이전트 오케스트레이터 내부 구조 (Multi-agent orchestrator internals) - 🚢 docs/DEPLOYMENT.md

— 운영 배포 옵션 (Production deployment options)

MIT. LICENSE를 참조하세요.

AI 자동 생성 콘텐츠

본 콘텐츠는 GitHub AI Tools의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0