중앙 집중식 거버넌스(Governance), 디스커버리(Discovery), 관측성(Observability)을 통해 MCP, A2A, REST/gRPC API를 연합하는 오픈 소스 레지스트리(Registry) 및 프록시(Proxy)입니다. 에이전트(Agent) 및 도구(Tool) 호출을 최적화하며 플러그인(Plugin)을 지원합니다.

ContextForge는 도구, 에이전트, API를 AI 클라이언트를 위한 하나의 깔끔한 엔드포인트(Endpoint)로 연합하는 오픈 소스 레지스트리 및 프록시입니다. AI 인프라 전반에 걸쳐 중앙 집중식 거버넌스, 디스커버리, 관측성을 제공합니다:

도구 게이트웨이 (Tools Gateway)— MCP, REST, gRPC-to-MCP 변환, 그리고 TOON 압축
에이전트 게이트웨이 (Agent Gateway)— A2A 프로토콜, OpenAI 호환 및 Anthropic 에이전트 라우팅(Routing)
API 게이트웨이 (API Gateway)— REST 서비스에 대한 속도 제한(Rate limiting), 인증(Auth), 재시도(Retries), 리버스 프록시(Reverse proxy)
플러그인 확장성 (Plugin Extensibility)— 추가적인 전송(Transports), 프로토콜, 통합을 위한 40개 이상의 플러그인
관측성 (Observability)— Phoenix, Jaeger, Zipkin 및 기타 OTLP 백엔드를 이용한 OpenTelemetry 트레이싱(Tracing)

이 시스템은 완전히 준수하는 MCP 서버로서 작동하며, PyPI 또는 Docker를 통해 배포할 수 있고, Redis 기반의 연합(Federation) 및 캐싱(Caching)을 통해 Kubernetes의 멀티 클러스터(Multi-cluster) 환경으로 확장 가능합니다.

• 개요 및 목표 (Overview & Goals)
• 빠른 시작 - PyPI (Quick Start - PyPI)
• 빠른 시작 - 컨테이너 (Quick Start - Containers)
• VS Code 개발 컨테이너 (VS Code Dev Container)
• 설치 (Installation)
• 업그레이드 (Upgrading)
• 설정 (Configuration)
• 실행 (Running)
• 클라우드 배포 (Cloud Deployment)
• API 레퍼런스 (API Reference)
• 테스트 (Testing)
• 프로젝트 구조 (Project Structure)
• 개발 (Development)
• 문제 해결 (Troubleshooting)
• 기여하기 (Contributing)

리소스 (Resource)	설명 (Description)
5분 설정 (5-Minute Setup)	빠르게 시작하기 — uvx, Docker, Compose 또는 로컬 개발
도움받기 (Getting Help)	지원 옵션, FAQ, 커뮤니티 채널
이슈 가이드 (Issue Guide)	버그 신고, 기능 요청, 기여 방법
전체 문서 (Full Documentation)	완전한 가이드, 튜토리얼, API 레퍼런스

ContextForge는 모든 Model Context Protocol (MCP) 서버, A2A 서버 또는 REST/gRPC API를 연합하여 중앙 집중식 거버넌스, 디스커버리, 관측성을 제공하는 오픈 소스 레지스트리 및 프록시입니다. 에이전트 및 도구 호출을 최적화하며 플러그인을 지원합니다. 자세한 내용은 프로젝트 로드맵을 참조하세요.

현재 다음을 지원합니다:

• 여러 MCP 및 REST 서비스 간의 연합 (Federation)
• 외부 AI 에이전트 (OpenAI, Anthropic, 커스텀)를 위한 A2A (Agent-to-Agent) 통합
• 자동 리플렉션 기반 서비스 디스커버리 (Service Discovery)를 통한 gRPC-to-MCP 변환
• 레거시 API를 MCP 준수 도구 및 서버로 가상화
• HTTP, JSON-RPC, WebSocket, SSE (구성 가능한 keepalive 포함), stdio 및 streamable-HTTP를 통한 전송
• 실시간 관리, 설정 및 로그 모니터링을 위한 관리자 UI (에어갭 (airgapped) 배포 지원)
• 사용자 범위의 OAuth 토큰 및 무조건적인 X-Upstream-Authorization 헤더 지원을 포함한 내장 인증, 재시도 및 속도 제한 (Rate-limiting)
• Phoenix, Jaeger, Zipkin 및 기타 OTLP 백엔드를 통한 OpenTelemetry 관찰성 (Observability)
• Docker 또는 PyPI를 통한 확장 가능한 배포, Redis 기반 캐싱 및 멀티 클러스터 연합

향후 기능 목록은 ContextForge 로드맵을 확인하세요.

🔌 프로토콜 유연성을 갖춘 게이트웨이 계층 (Gateway Layer)

• 모든 MCP 서버 또는 REST API를 연합
• MCP 프로토콜 버전 선택 가능 (예: 2025-11-25)
• 다양한 백엔드를 위한 단일화된 통합 인터페이스 노출

🧩 REST/gRPC 서비스의 가상화

• 비(non)-MCP 서비스를 가상 MCP 서버로 래핑 (Wrap)
• 최소한의 설정으로 도구 (Tools), 프롬프트 (Prompts), 리소스 (Resources) 등록
• 서버 리플렉션 프로토콜을 통한 gRPC-to-MCP 변환
• 자동 서비스 디스커버리 및 메서드 인트로스펙션 (Introspection)

🔁 REST-to-MCP 도구 어댑터

• REST API를 다음 기능을 갖춘 도구로 변환:
  • 자동 JSON 스키마 (Schema) 추출
  • 헤더, 토큰 및 커스텀 인증 지원
  • 재시도, 타임아웃 및 속도 제한 정책

🧠 통합 레지스트리 (Unified Registries)

• 프롬프트 (Prompts): Jinja2 템플릿, 멀티모달 (Multimodal) 지원, 롤백/버전 관리
• 리소스 (Resources): URI 기반 액세스, MIME 감지, 캐싱, SSE 업데이트
• 도구 (Tools): 네이티브 또는 변환된 도구, 입력 검증 및 동시성 제어 포함

📈 관리자 UI, 관찰성 및 개발자 경험 (Dev Experience)

• HTMX 2.0.3 (bundled) + Alpine.js로 구축된 관리자 UI (Admin UI)
• 필터링, 검색 및 내보내기 기능을 갖춘 실시간 로그 뷰어 (Real-time log viewer)
• 인증 (Auth): Basic, JWT 또는 커스텀 스킴 (custom schemes)
• 구조화된 로그 (Structured logs), 상태 확인 엔드포인트 (health endpoints), 메트릭 (metrics)
• 7,000개 이상의 테스트, Makefile 타겟, 라이브 리로드 (live reload), 프리커밋 훅 (pre-commit hooks)

🔍 OpenTelemetry 관찰성 (Observability)

• OpenTelemetry (OTLP) 프로토콜 지원을 통한 벤더 중립적 트레이싱 (Vendor-agnostic tracing)
• 다양한 백엔드 지원: Phoenix (LLM 중심), Jaeger, Zipkin, Tempo, DataDog, New Relic
• 연합 게이트웨이 (federated gateways) 및 서비스 전반에 걸친 분산 트레이싱 (Distributed tracing)
• 도구, 프롬프트, 리소스 및 게이트웨이 작업에 대한 자동 계측 (Automatic instrumentation)
• LLM 특화 메트릭 (LLM-specific metrics): 토큰 사용량 (Token usage), 비용 (costs), 모델 성능 (model performance)
• 비활성화 시 오버헤드 제로 (Zero-overhead) 및 우아한 성능 저하 (graceful degradation)

Phoenix, Jaeger 및 기타 백엔드를 사용한 설정 가이드는 **관찰성 문서 (Observability Documentation)**를 참조하세요.

ContextForge는 PyPI에 mcp-contextforge-gateway로 게시되어 있습니다.

TLDR;:
(uv를 사용한 단일 명령)

# 환경 변수를 사용한 빠른 시작
BASIC_AUTH_PASSWORD=pass \
MCPGATEWAY_UI_ENABLED=true \
...

📋 사전 요구 사항 (Prerequisites)

• Python ≥ 3.11
• curl + jq - 마지막 스모크 테스트 (smoke-test) 단계에서만 필요

# 1️⃣ 격리된 환경 + PyPI에서 설치
mkdir mcpgateway && cd mcpgateway
python3 -m venv .venv && source .venv/bin/activate
...

Windows (PowerShell) 빠른 시작

# 1️⃣ 격리된 환경 + PyPI에서 설치
mkdir mcpgateway ; cd mcpgateway
python3 -m venv .venv ; .\.venv\Scripts\Activate.ps1
...

⚡ 대안: uv (더 빠름)

# 1️⃣ 격리된 환경 + uv를 사용하여 PyPI에서 설치
mkdir mcpgateway ; cd mcpgateway
uv venv
...

추가 설정 (More configuration)

.env.example 파일을 .env로 복사한 뒤

모든 설정을 조정하거나(또는 환경 변수로 사용) 하세요.

🚀 엔드 투 엔드 데모 (로컬 MCP 서버 등록)

# 1️⃣ mcpgateway.translate 및 docker를 사용하여 샘플 GO MCP 시간 서버 실행 (필요한 경우 docker를 podman으로 교체)
python3 -m mcpgateway.translate \
--stdio "docker run --rm -i ghcr.io/ibm/fast-time-server:latest -transport=stdio" \
...

🖧 stdio 래퍼 (mcpgateway-wrapper) 사용하기

export MCP_AUTH="Bearer ${MCPGATEWAY_BEARER_TOKEN}"
export MCP_SERVER_URL=http://localhost:4444/servers/UUID_OF_SERVER_1/mcp
python3 -m mcpgateway.wrapper # 종료하려면 Ctrl-C

uv를 사용하여 실행할 수도 있습니다.

또는 Docker/Podman 내부에서 실행할 수도 있습니다 - 위의 Containers 섹션을 참조하세요.

MCP Inspector에서 MCP_AUTH와 MCP_SERVER_URL 환경 변수 (env variables)를 정의하고, Command로 python3를, Arguments로 -m mcpgateway.wrapper를 선택하세요.

echo $PWD/.venv/bin/python3 # Python3 전체 경로를 사용하면 작동하는 venv를 확보할 수 있습니다
export MCP_SERVER_URL='http://localhost:4444/servers/UUID_OF_SERVER_1/mcp'
export MCP_AUTH="Bearer ${MCPGATEWAY_BEARER_TOKEN}"
...

또는

URL과 인증 (auth) 정보를 인자 (arguments)로 전달하세요 (환경 변수를 설정할 필요가 없습니다).

npx -y @modelcontextprotocol/inspector
command: `python`
Arguments: `-m mcpgateway.wrapper --url "http://localhost:4444/servers/UUID_OF_SERVER_1/mcp" --auth "Bearer <your token>"`

stdio를 사용하는 Claude와 같은 MCP 클라이언트 (Client)를 사용할 때:

{
"mcpServers": {
"mcpgateway-wrapper": {
...

Docker 또는 Podman을 사용하여 GHCR의 공식 OCI 이미지를 사용하세요.
주의 사항: 현재 프로덕션 (production) 환경에서는 arm64가 지원되지 않습니다. 예를 들어 Apple Silicon 칩(M1, M2 등)이 탑재된 MacOS에서 실행 중인 경우, Rosetta를 사용하여 컨테이너를 실행하거나 대신 PyPi를 통해 설치할 수 있습니다.

PostgreSQL 및 Redis를 포함한 전체 스택을 30초 이내에 실행하세요:

# 스택을 클론(Clone)하고 시작합니다
git clone https://github.com/IBM/mcp-context-forge.git
cd mcp-context-forge
...

제공되는 기능:

제공되는 기능:

• 🗄️ PostgreSQL- 55개 이상의 테이블을 포함한 프로덕션 준비 완료(Production-ready) 데이터베이스 - 🚀
• ContextForge- 관리자 UI(Admin UI)를 갖춘 풀 기능 게이트웨이(Full-featured gateway) - 📊
• Redis- 고성능 캐싱(Caching) 및 세션 저장소(Session storage) - 🔧
• Admin Tools- 데이터베이스 관리를 위한 pgAdmin, Redis Insight - 🌐
• Nginx Proxy- 8080 포트의 캐싱 리버스 프록시(Caching reverse proxy)

HTTPS 활성화 (선택 사항):

# TLS를 활성화하여 시작 (자가 서명 인증서 자동 생성)
make compose-tls
# HTTPS를 통해 접속: https://localhost:8443/admin
...

엔터프라이즈급 기능을 갖춘 Kubernetes로 배포:

# Helm 저장소 추가 (사용 가능 시)
# helm repo add mcp-context-forge https://ibm.github.io/mcp-context-forge
# helm repo update
...

SSRF 참고: Helm은 엄격한 SSRF 설정을 기본값으로 사용합니다 (SSRF_ALLOW_PRIVATE_NETWORKS=false). 클러스터 내부의 도구 URL(예: fast-time 또는 fast-test 서비스)을 등록하는 경우, mcpContextForge.config.SSRF_ALLOWED_NETWORKS를 통해 클러스터 CIDR만 허용하거나, 로컬 전용 벤치마크 설정의 경우 일시적으로 SSRF_ALLOW_PRIVATE_NETWORKS=true로 설정하십시오. docs/docs/manage/configuration.md#ssrf-protection 및 docs/docs/deployment/helm.md를 참조하십시오.

엔터프라이즈 기능 (Enterprise Features):

• 🔄 Auto-scaling- CPU/메모리 타겟을 사용한 HPA (Horizontal Pod Autoscaler) - 🗄️
• Database Choice- PostgreSQL (운영 환경), SQLite (개발 환경) - 📊
• Observability- Prometheus 메트릭(Metrics), OpenTelemetry 트레이싱(Tracing) - 🔒
• Security- RBAC (역할 기반 액세스 제어), 네트워크 정책(Network policies), 비밀 관리(Secret management) - 🚀
• High Availability- Redis 클러스터링을 이용한 멀티 레플리카(Multi-replica) 배포 - 📈
• Monitoring- 내장된 Grafana 대시보드 및 알림(Alerting)

docker run -d --name mcpgateway \
-p 4444:4444 \
-e MCPGATEWAY_UI_ENABLED=true \
...

**http://localhost:4444/admin**으로 접속하여 PLATFORM_ADMIN_EMAIL / PLATFORM_ADMIN_PASSWORD로 로그인하십시오.

고급: 영구 스토리지(Persistent storage), 호스트 네트워킹(Host networking), 에어갭(Airgapped)

SQLite 데이터베이스 영구 저장:

mkdir -p $(pwd)/data && touch $(pwd)/data/mcp.db && chmod 777 $(pwd)/data
docker run -d --name mcpgateway --restart unless-stopped \
-p 4444:4444 -v $(pwd)/data:/data \
...

호스트 네트워킹 (Host networking) (로컬 MCP 서버 접근):**

docker run -d --name mcpgateway --network=host \
-v $(pwd)/data:/data -e DATABASE_URL=sqlite:////data/mcp.db \
-e MCPGATEWAY_UI_ENABLED=true -e HOST=0.0.0.0 -e PORT=4444 \
...

에어갭 배포 (Airgapped deployment) (인터넷 연결 없음):**

docker build -f Containerfile.lite -t mcpgateway:airgapped .
docker run -d --name mcpgateway -p 4444:4444 \
-e MCPGATEWAY_UI_AIRGAPPED=true -e MCPGATEWAY_UI_ENABLED=true \
...

podman run -d --name mcpgateway \
-p 4444:4444 -e HOST=0.0.0.0 -e DATABASE_URL=sqlite:///./mcp.db \
ghcr.io/ibm/mcp-context-forge:1.0.0-RC-3

고급 설정: 영구 저장소, 호스트 네트워킹 (Advanced: Persistent storage, host networking)

SQLite 데이터베이스 유지:

mkdir -p $(pwd)/data && chmod 777 $(pwd)/data
podman run -d --name mcpgateway --restart=on-failure \
-p 4444:4444 -v $(pwd)/data:/data \
...

호스트 네트워킹:

podman run -d --name mcpgateway --network=host \
-v $(pwd)/data:/data -e DATABASE_URL=sqlite:////data/mcp.db \
ghcr.io/ibm/mcp-context-forge:1.0.0-RC-3

✏️ Docker/Podman 팁

• .env 파일: 모든 -e FOO= 라인을 하나의 파일에 넣고, 이를 --env-file .env로 대체하세요.
  참고는 제공된 .env.example을 참조하세요.

• 버전 고정 태그 (Pinned tags): 재현 가능한 빌드를 위해 latest 대신 명시적인 버전(예: 1.0.0-RC-3)을 사용하세요.

• JWT 토큰: 실행 중인 컨테이너에서 다음 명령어로 생성하세요:
  docker exec mcpgateway python3 -m mcpgateway.utils.create_jwt_token --username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes

• 업그레이드: 동일한 -v $(pwd)/data:/data 마운트를 사용하여 중지, 제거 후 다시 실행하면 데이터베이스와 설정이 온전하게 유지됩니다.

🚑 실행 중인 컨테이너에 대한 스모크 테스트 (Smoke-test the running container)

curl -s -H

JWT 인증을 유지하면서 **표준 입출력 (stdio)**를 통해 게이트웨이에 연결할 수 있게 해줍니다. 이는 MCP 클라이언트에서 실행해야 합니다. 아래 예시는 테스트용입니다.

환경 변수 설정

export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token --username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes)
export MCP_AUTH="Bearer ${MCPGATEWAY_BEARER_TOKEN}"
...

저장소를 클론하고 VS Code에서 열면 `.devcontainer`를 감지하여 **"컨테이너에서 다시 열기 (Reopen in Container)\