abdullah1854/MCPGateway

15단계의 토큰 최적화(95-98% 감소)를 통해 300개 이상의 도구를 단일 엔드포인트로 라우팅하는 범용 MCP 집계 서버(Universal MCP aggregation server)입니다. Claude Desktop, Claude Code, Cursor, OpenAI Codex 및 VS Code Copilot과 함께 작동합니다.

멀티 서버 집계 (Multi-Server Aggregation)— 하나의 게이트웨이 엔드포인트를 통해 여러 MCP 서버(STDIO, HTTP, SSE)를 연결합니다.
15단계 토큰 최적화 (15 Token Optimization Layers)— 점진적 공개(Progressive disclosure), 스마트 필터링, 집계, 코드 배치(code batching), 델타 응답(delta responses), 자동 요약(auto-summarization) 등을 제공합니다.
웹 대시보드 (Web Dashboard)— 도구, 백엔드 및 서버 라이프사이클을 핫 리로드(hot-reload)와 함께 관리할 수 있는 실시간 UI를 제공합니다.
샌드박스 코드 실행 (Sandboxed Code Execution)— 배치 작업을 위해 보안 Node.js VM에서 TypeScript/JavaScript를 실행합니다.
스킬 시스템 (Skills System)— 제로샷(zero-shot) 작업 실행을 위해 코드 패턴을 저장하고 재사용합니다.
인증 (Authentication)— API Key 및 OAuth/JWT를 지원하며 속도 제한(rate limiting) 기능이 포함되어 있습니다.
Docker 지원 (Docker Ready)— Docker/Compose를 통한 간편한 배포가 가능합니다.

git clone https://github.com/abdullah1854/MCPGateway.git
cd MCPGateway
npm install
...

Claude Desktop / Cursor / VS Code Copilot — 원격 MCP 서버로 추가:

Claude Code — 설정에 추가:

{
"mcpServers": {
"mcp-gateway": {
...

대시보드 (Dashboard): http://localhost:3010/dashboard

최적의 사용 사례: 하나의 MCP 엔드포인트, 브라우저 대시보드, 그리고 수많은 도구를 사용할 때 공격적인 토큰 절약을 원하는 팀에게 적합합니다.

빠른 시작 (Quick start)
지원되는 클라이언트 (Supported clients)
대시보드 스크린샷 (Dashboard screenshots)
백엔드 설정 (Backend configuration)
보안 모드 (Security modes)
예시 (Examples)
이슈 및 지원 (Issues & support)

npm install
cp config/servers.example.json config/servers.json
npm run dev

그 다음 http://localhost:3010/dashboard를 열고,

선호하는 클라이언트를 연결한 후, 서버 구성 및 프로덕션 설정을 위해 아래의 전체 빠른 시작(Quick Start) 가이드를 계속 진행하세요.

클라이언트 (Client)	지원 여부	비고
Claude Desktop	✅	게이트웨이의 HTTP 또는 SSE 엔드포인트를 통해 연결
...

2025년 1월: Anthropic은 defer_loading과 정규 표현식(regex)/BM25 검색을 사용하여 대규모 카탈로그에서 도구를 검색할 수 있는 서버 측 네이티브 기능인 Tool Search Tool을 출시했습니다.

MCP Gateway와 Anthropic의 Tool Search는 서로 다른 문제를 해결합니다:

문제	Anthropic Tool Search	MCP Gateway
도구 검색 (Tool Discovery) (수백 개 중 적절한 도구 찾기)	✅ 네이티브 `defer_loading` + 검색	✅ 점진적 공개 (Progressive disclosure)
결과 필터링 (Result Filtering) (대규모 결과 축소)	❌ 지원되지 않음	✅ `maxRows`, `fields`, `format`
자동 요약 (Auto-Summarization) (통찰력 추출)	❌ 지원되지 않음	✅ 60-90% 토큰 절감
델타 응답 (Delta Responses) (변경 사항만 전송)	❌ 지원되지 않음	✅ 폴링 (Polling) 시 90% 이상 절감
집계 (Aggregations) (count, sum, groupBy)	❌ 지원되지 않음	✅ 서버 측 분석 (Server-side analytics)
코드 배치 (Code Batching) (한 번의 호출로 여러 작업 수행)	❌ 지원되지 않음	✅ 왕복 시간 (Round-trips) 60-80% 감소
스킬 (Skills) (재사용 가능한 코드 패턴)	❌ 지원되지 않음	✅ 95% 이상 토큰 절감

결론: Anthropic의 Tool Search는 적절한 도구를 찾는(find) 것을 도와줍니다. MCP Gateway는 대규모 결과를 관리하고, 작업을 배치하며, 재사용 가능한 패턴을 제공함으로써 도구를 효율적으로 사용(use) 하도록 도와줍니다.

두 기능을 함께 사용할 수 있습니다. Anthropic이 도구 검색을 처리하게 하고, 도구 *호출(calls)*은 결과 최적화를 위해 MCP Gateway를 통해 라우팅하십시오.

문제: AI 에이전트가 MCP 서버와 작업할 때 세 가지 결정적인 문제에 직면합니다:

도구 과부하 (Tool Overload) - 300개 이상의 도구 정의를 로드하면 작업이 시작되기도 전에 77,000개 이상의 컨텍스트 토큰을 소비합니다.
결과 비대화 (Result Bloat) - 대규모 쿼리 결과(10,000행)는 호출당 50,000개 이상의 토큰을 소비할 수 있습니다.
반복적인 작업 (Repetitive Operations) - 동일한 워크플로우를 매번 모델에게 다시 설명해야 합니다.

참고: Anthropic의 Tool Search Tool은 이제 직접 API를 사용하는 사용자를 위해 1번 문제를 네이티브하게 해결합니다. MCP Gateway는 2번과 3번 문제를 해결하는 데 여전히 필수적이며, 네이티브 도구 검색 기능이 없는 MCP 클라이언트를 위한 도구 검색 기능도 제공합니다.

해결책 (Solution): MCP Gateway는 모든 MCP 서버를 통합하며 15단계의 토큰 최적화 (token optimization) 레이어를 제공합니다:

레이어 (Layer)	기능 (What It Does)	토큰 절감 (Token Savings)	Gateway만의 고유 기능? (Unique to Gateway?)
점진적 공개 (Progressive Disclosure)	도구 스키마 (tool schemas)를 필요할 때만 로드	85%	공유됨*
스마트 필터링 (Smart Filtering)	결과 크기를 자동으로 제한	60-80%	✅
집계 (Aggregations)	서버 측 분석 (Server-side analytics)	90%+	✅
코드 배치 (Code Batching)	한 번의 호출로 여러 작업 수행	60-80%	✅
기술 (Skills)	제로샷 (Zero-shot) 작업 실행	95%+	✅
캐싱 (Caching)	반복되는 쿼리 건너뛰기	100%	✅
PII 토큰화 (PII Tokenization)	민감한 데이터 삭제 (Redact)	보안 (Security)	✅
응답 최적화 (Response Optimization)	null/빈 값 제거	20-40%	✅
...	델타 응답 (Delta Responses)	반복 쿼리에 대해 변경 사항만 전송	90%+
컨텍스트 추적 (Context Tracking)	컨텍스트 사용량을 모니터링하여 오버플로 방지	안전 (Safety)	✅
자동 요약 (Auto-Summarization)	대규모 결과에서 통찰력 추출	60-90%	✅
쿼리 계획 (Query Planning)	최적화 기회 감지	30-50%	✅

**Anthropic의 도구 검색 (Tool Search)은 네이티브 도구 발견 기능을 제공하며, MCP Gateway는 네이티브 지원이 없는 MCP 클라이언트를 위해 이 기능을 제공합니다.

결과 (Result): 일반적인 세션에서 토큰 사용량이 약 500,000개에서 약 25,000개로 감소합니다 (95% 감소).

Cursor가 MCP Gateway에 연결됨 - 19개의 도구가 16개 서버에 걸친 305개의 백엔드 도구에 대한 액세스 제공

Claude Code /context 뷰 - 원시 정의 (raw definitions) 사용 시 200k+ 토큰이 필요한 대신, 모든 MCP 도구에 대해 단 8.9k 토큰 (4.5%)만 사용

Gateway MCP 도구 (Gateway MCP Tools) - 모든 코드 실행 기능이 이제 MCP 도구로 노출됩니다 (gateway_*

)를 통해 어떤 클라이언트든 직접 발견하고 사용할 수 있습니다.핫 리로드 서버 관리 (Hot-Reload Server Management)- 서버 재시작 없이 대시보드에서 MCP 서버를 추가, 편집 및 삭제할 수 있습니다.UI 상태 유지 (UI State Persistence)- 비활성화된 도구 및 백엔드 설정이 서버 재시작 후에도 유지됩니다.향상된 대시보드 (Enhanced Dashboard)- 실패한 백엔드 재연결, 실시간 상태 확인, 개선된 에러 핸들링(error handling)연결 테스트 (Connection Testing)- 설정을 추가하기 전에 서버 연결을 테스트할 수 있습니다.설정 내보내기/가져오기 (Export/Import Config)- 서버 설정을 쉽게 백업하고 공유할 수 있습니다.병렬 도구 실행 (Parallel Tool Execution)- 더 나은 성능을 위해 여러 도구 호출을 동시에 실행합니다.결과 필터링 및 집계 (Result Filtering & Aggregation)- maxRows, fields, format 및 집계 옵션을 사용하여 컨텍스트 팽창(context bloat)을 줄입니다.

🔀 멀티 서버 집계 (Multi-Server Aggregation)- 하나의 게이트웨이를 통해 여러 MCP 서버를 라우팅합니다. - 🎛️ 웹 대시보드 (Web Dashboard)- 도구, 백엔드 및 서버 라이프사이클을 관리하기 위한 실시간 UI - ➕ 핫 리로드 서버 관리 (Hot-Reload Server Management)- 서버 재시작 없이 대시보드에서 MCP 서버를 추가, 편집, 삭제합니다. - 🌐 HTTP 스트리밍 가능 전송 (HTTP Streamable Transport)- 모든 클라이언트와 작동하는 기본 전송 방식 - 📡 SSE 전송 (SSE Transport)- 이전 클라이언트와의 하위 호환성 제공 - 🔐 인증 (Authentication)- API Key 및 OAuth/JWT 지원 - ⚡ 속도 제한 (Rate Limiting)- 백엔드 서버를 보호합니다 - 🐳 Docker 지원 (Docker Ready)- Docker/Compose를 통한 쉬운 배포 - 📊 상태 확인 (Health Checks)- 상세한 진단 기능으로 백엔드 상태를 모니터링합니다 - 🔄 자동 재시작 (Auto-Restart)- 충돌 발생 시 또는 대시보드를 통해 서버가 자동으로 재시작됩니다 - 💾 UI 상태 유지 (UI State Persistence)- 재시작 후에도 비활성화된 도구/백엔드를 기억합니다

Anthropic의 MCP를 이용한 코드 실행(Code Execution with MCP)에서 영감을 얻어 - 최대 98.7%의 토큰 감소를 달성합니다:

🔍
점진적 도구 공개 (Progressive Tool Disclosure)- 토큰 사용량을 줄이기 위해 도구를 검색하고 지연 로딩 (Lazy-load) 수행 (85% 감소) - 💻
샌드박스 코드 실행 (Sandboxed Code Execution)- 보안이 강화된 Node.js VM에서 TypeScript/JavaScript 실행 - 📉
문맥 효율적 결과 (Context-Efficient Results)- 도구 결과값을 필터링, 집계 및 변환 (60-80% 감소) - 🔒
개인정보 보호 작업 (Privacy-Preserving Operations)- 민감한 데이터에 대한 개인정보(PII) 토큰화 수행 - 📁
기술 시스템 (Skills System)- 제로샷 실행 (Zero-shot execution)을 위해 코드 패턴을 저장하고 재사용 (프롬프트 토큰 제거) - 🗄️
상태 지속성 (State Persistence)- 세션 간 에이전트 상태를 유지하기 위한 워크스페이스 제공 - 🛠️
Gateway MCP 도구 (Gateway MCP Tools)- 모든 코드 실행 기능을 모든 클라이언트에서 사용할 수 있도록 MCP 도구로 노출 - 🧹
응답 최적화 (Response Optimization)- 응답에서 null 또는 빈 값을 자동으로 제거 (20-40% 감소) - 🧠
세션 문맥 (Session Context)- 다회차 대화 (Multi-turn conversations)에서 데이터 재전송을 방지하기 위해 전송된 데이터 추적 - 🔗
스키마 중복 제거 (Schema Deduplication)- 해시(Hash)를 통해 동일한 스키마를 참조 (최대 90% 감소) - 📐
마이크로 스키마 모드 (Micro-Schema Mode)- 약어 타입을 사용한 초소형 스키마 (60-70% 감소) - 🔄
델타 응답 (Delta Responses)- 반복되는 쿼리에 대해 변경 사항만 전송 (90% 이상 감소) - 📊
문맥 추적 (Context Tracking)- 문맥 창 (Context window) 사용량을 모니터링하고 오버플로 발생 전 경고 제공 - 📝
자동 요약 (Auto-Summarization)- 대규모 결과에서 핵심 통찰 추출 (60-90% 감소) - 🔍
쿼리 계획 (Query Planning)- 최적화 기회를 감지하기 위해 코드를 분석 (30-50% 개선)
📈
Prometheus 메트릭 (Prometheus Metrics)- 도구 호출 지연 시간 (Latency), 에러율, 캐시 성능 - 📊
JSON 메트릭 API (JSON Metrics API)- 게이트웨이 통계에 대한 프로그래밍 방식의 접근 - 💾
결과 캐싱 (Result Caching)- 도구 결과에 대해 TTL이 적용된 LRU 캐시 사용 - 📝
감사 로그 (Audit Logging)- 민감한 작업 추적

npm install

예시 설정을 복사하여 수정하세요:

cp config/servers.example.json config/servers.json

config/servers.json을 편집하여

사용자의 MCP 서버를 추가하세요:

{
"servers": [
{
...

# 개발 (Development)
npm run dev
# 운영 (Production)
...

게이트웨이는 기본적으로 http://localhost:3010에서 시작됩니다.

로컬 실험을 위해 인증 없이 실행하려면 다음과 같이 입력하세요:

AUTH_MODE=none

하지만, AUTH_MODE=none 설정 시 민감한 엔드포인트 (sensitive endpoints) (/dashboard, /dashboard/api/*, /api/code/*, /metrics/json)는 기본적으로 차단됩니다. 인증되지 않은 접근을 허용하려면 (격리된 로컬 사용 용도 외에는 권장하지 않음), 명시적으로 다음 설정을 추가해야 합니다:

ALLOW_INSECURE=1

안전한 사용을 위해서는 다음 설정을 권장합니다:

API_KEYS=key1,key2와 함께 사용하는 AUTH_MODE=api-key

또는

아래에 표시된 적절한 OAUTH_* 설정과 함께 사용하는 AUTH_MODE=oauth

엔드포인트 (Endpoint)	전송 방식 (Transport)	사용 사례 (Use Case)
`/mcp`	HTTP 스트리밍 가능 (HTTP Streamable)	기본 엔드포인트 - 모든 클라이언트와 작동
`/sse`	서버 전송 이벤트 (Server-Sent Events)	하위 호환성
`/health`	JSON	상태 확인 (Health checks) 및 상태
`/dashboard`	웹 UI (Web UI)	도구, 백엔드 관리 및 서버 재시작
`/metrics`	Prometheus	Prometheus 형식의 메트릭 (metrics)
`/metrics/json`	JSON	JSON 형식의 메트릭 (metrics)

엔드포인트 (Endpoint)	메서드 (Method)	설명 (Description)
`/api/code/tools/search`	GET	필터를 사용하여 도구 검색
`/api/code/tools/tree`	GET	파일 시스템과 유사한 도구 트리 가져오기
`/api/code/tools/names`	GET	모든 도구 이름 가져오기 (최소 토큰)
`/api/code/tools/:name/schema`	GET	특정 도구 스키마 (schema) 지연 로드
`/api/code/tools/stats`	GET	백엔드별 도구 통계
`/api/code/sdk`	GET	자동 생성된 TypeScript SDK
`/api/code/execute`	POST	샌드박스 (sandbox) 내에서 코드 실행
`/api/code/tools/:name/call`	POST	결과 필터링을 포함한 도구 호출
`/api/code/tools/:name/call/aggregate`	POST	집계 (aggregation)를 포함한 도구 호출
`/api/code/tools/parallel`	POST	여러 도구를 병렬로 실행
`/api/code/skills`	GET/POST	스킬 (skills) 목록 조회 또는 생성
`/api/code/skills/search`	GET	스킬 검색
`/api/code/skills/:name`	GET/DELETE	스킬 가져오기 또는 삭제
`/api/code/skills/:name/execute`	POST	스킬 실행
`/api/code/workspace/session`	GET/POST	세션 상태 가져오기 또는 업데이트
`/api/code/cache/stats`	GET	캐시 (cache) 통계
`/api/code/cache/clear`	POST	캐시 삭제

Endpoint	Method	Description
`/dashboard/api/tools`	GET	활성화 상태인 모든 도구 (tools) 가져오기
`/dashboard/api/backends`	GET	상태 정보가 포함된 모든 백엔드 (backends) 가져오기
`/dashboard/api/tools/:name/toggle`	POST	도구의 활성화/비활성화 전환
`/dashboard/api/backends/:id/toggle`	POST	백엔드의 활성화/비활성화 전환
`/dashboard/api/backends/:id/reconnect`	POST	실패한 백엔드 재연결
`/dashboard/api/backends`	POST	새로운 백엔드 서버 추가
`/dashboard/api/backends/:id`	PUT	백엔드 설정 업데이트
`/dashboard/api/backends/:id`	DELETE	백엔드 서버 삭제
`/dashboard/api/config/export`	GET	서버 설정 내보내기
`/dashboard/api/config/import`	POST	서버 설정 가져오기
`/dashboard/api/restart`	POST	게이트웨이 (gateway) 서버 재시작

웹 대시보드는 http://localhost:3010/dashboard에서 접속할 수 있습니다.

다음 기능을 수행할 수 있습니다:

연결된 모든 백엔드와 실시간 상태 확인
새로운 MCP 서버 추가 (연결 테스트 포함: STDIO, HTTP, SSE 전송 방식)
기존 서버 편집 (명령어, 인자(args), 환경 변수 수정)
서버 삭제 (안전한 연결 해제 포함)
개별 도구 또는 전체 백엔드의 활성화/비활성화
모든 백엔드에 걸친 도구 검색 및 필터링
백업 및 공유를 위한 설정 내보내기/가져오기
클릭 한 번으로 실패한 백엔드 재연결
전체 게이트웨이 서버 재시작
도구 개수 및 백엔드 상태를 한눈에 확인

대시보드는 서버 재시작 시에도 UI 상태(비활성화된 도구/백엔드)를 유지합니다.

Claude Desktop 실행 →
Settings → Connectors - Add remote MCP server 클릭 → 게이트웨이 URL 입력:

필요한 경우 인증 완료

참고: Claude는 설정 파일이 아닌 UI를 통해 원격 서버를 추가해야 합니다.

abdullah1854/MCPGateway

요약

핵심 포인트

댓글