MCP Gateway

자체 호스팅 Model Context Protocol 서버용 컨트롤 플레인입니다. 사용하는 모든 MCP 서버를 한곳에서 정의하고, 웹 GUI에서 관리하며, 에이전트에 단일 엔드포인트를 제공하세요 — 서버별로 또는 네임스페이스된 도구를 갖춘 서버 그룹 전체에 대해.

 Claude Code · Claude Desktop · Cursor · VS Code · your agent
        │  Streamable HTTP  /mcp/servers/<id>   /mcp/groups/<id>      (+ API key)
        ▼
 ┌────────────────────── MCP Gateway ──────────────────────┐
 │  web GUI  ·  admin REST API  ·  sessions  ·  logs        │
 │  groups: namespaced tools  pg-analytics__execute_sql …   │
 │  upstream manager: start/stop, restart w/ backoff,       │
 │  health checks, idle stop, tool filters & renames        │
 └───────┬──────────────────┬──────────────────┬───────────┘
   stdio (npx/uvx/docker)   Streamable HTTP     legacy SSE
   Postgres, filesystem…    remote MCP servers  older servers

시나리오. 에이전트가 두 개의 Postgres 데이터베이스를 필요로 합니다. GUI에서 pg-analytics와 pg-orders를 추가하고(PostgreSQL (DBHub) 템플릿 사용), databases 그룹에 넣은 다음 에이전트를 http://gateway:8808/mcp/groups/databases로 지정합니다. 에이전트는 pg-analytics__execute_sql과 pg-orders__execute_sql을 볼 수 있으며, 게이트웨이가 프로세스, 자격 증명, 재시작 및 로그를 소유합니다. 완전하고 실행 가능한 버전은 examples/postgres-scenario에 있습니다.

기능

• 모든 업스트림 전송 — stdio 프로세스(npx, uvx, docker run, 그 외 무엇이든), Streamable HTTP 및 bearer/basic/header 인증을 지원하는 레거시 SSE 원격 서버.

• 수명주기 관리 — 자동/지연 시작, 유휴 중지, 상한이 있는 지수 백오프 재시작, 상태 확인 핑, 시작/요청/도구 호출 타임아웃, 캡처된 stderr.

• 그룹 — 하나의 엔드포인트 뒤에 여러 서버; 도구와 프롬프트에 네임스페이스 적용(prefix__tool, . 또는 -), 또는 충돌 처리를 통한 통과(pass-through); 멤버별 필터; 결합된 지침; 암시적 all 그룹.

• 도구 정책 — 서버별 도구의 포함/제외 glob 패턴, 숨기기, 이름 바꾸기, 설명 다시 쓰기.

• 전체 MCP 프록시 — 도구, 리소스(+템플릿, 구독), 프롬프트, 자동 완성, 로깅, 진행률, 취소, list_changed 전파, 그리고 원래 세션으로 다시 라우팅되는 서버→클라이언트 샘플링/elicitation/루트.

• 다운스트림 전송 — Streamable HTTP(재개 가능한 스트림을 지원하는 상태 유지, 또는 무상태), 레거시 SSE, 그리고 Claude Desktop 같은 클라이언트를 위한 stdio 브리지 mcp-gateway-connect.

• 보안 — API 키(해시 처리, 서버/그룹 범위 지정, 만료), GUI/API용 관리자 토큰, 비밀 값 삭제, ${ENV} 보간으로 비밀 값을 설정 파일에 절대 작성하지 않아도 됨, DNS 리바인딩 보호, CORS 허용 목록.

• GUI — 대시보드, 16개 템플릿이 포함된 서버 카탈로그(Postgres ×3, MySQL, SQLite, filesystem, GitHub, Playwright, Context7, fetch, memory, …), 연결 테스트가 포함된 탭 편집기, 사용해 보기가 포함된 도구 탐색기, 리소스/프롬프트 브라우저, 실시간 로그, 메트릭, 클라이언트별 연결 스니펫, 세션, 설정, 가져오기/내보내기(Claude Desktop / Cursor / VS Code mcpServers 파일).

Related MCP server: Master MCP Server

스크린샷

대시보드 — 실행 중인 서버, 그룹, 활성 세션 및 실시간 이벤트 피드:

서버 카탈로그 — 전송, 상태, 도구 수 및 재시작 수를 한눈에:

서버 상세 보기 — 런타임 및 엔드포인트 정보, 그리고 GUI에서 바로 도구를 호출할 수 있는 도구 탐색기:

빠른 시작

요구 사항: Node.js ≥ 20 (실행할 업스트림 서버에 따라 npx/uvx/docker 필요).

git clone <this repo> mcp-gateway && cd mcp-gateway
npm install
npm run build
npm start                     # → http://127.0.0.1:8808

그런 다음 GUI에서: 서버 → 서버 추가 → PostgreSQL (DBHub) → DSN 붙여넣기 → 연결 테스트 → 서버 생성. 서버의 연결 탭을 열고 클라이언트에 맞는 스니펫을 복사하세요. 예:

claude mcp add --transport http pg-analytics http://127.0.0.1:8808/mcp/servers/pg-analytics

개발 모드(Vite, :5173에서 핫 리로드, 게이트웨이는 :8808): npm run dev.

Docker

docker compose up -d --build              # GUI on http://localhost:8808, data in ./data

이미지에는 node/npx, uvx, git이 포함되어 있어 npm 기반 및 Python 기반 MCP 서버를 컨테이너 안에서 실행할 수 있습니다. 포트가 다른 사람에게 도달 가능한 경우 환경에 GATEWAY_ADMIN_TOKEN을 설정하세요. 구성을 미리 로드하려면 파일을 마운트하고 GATEWAY_SEED_CONFIG=/path/to/config.json을 설정하세요 — 처음 시작 시 데이터 볼륨에 복사됩니다.

구성 요소

구성은 단일 JSON 파일(data/config.json, 모드 0600, 원자적 쓰기, .bak 유지)입니다. 모든 필드는 docs/CONFIG.md를 참조하세요. 각 도구의 클라이언트 설정은 docs/CLIENTS.md에, 전체 설계는 docs/SPEC.md에 있습니다. GUI에는 게이트웨이 작동 방식과 서버 추가, 사용자 지정, 연결 방법을 안내하는 기본 제공 문서 페이지(/docs, 설정 옆)도 있습니다.

CLI

mcp-gateway serve [--host 127.0.0.1] [--port 8808] [--data-dir ./data] [--config <file>] [--public-url <url>] [--log-level info]
mcp-gateway import <file> [--format gateway|mcpServers] [--mode merge|replace]    # into the config file (restart to apply)
mcp-gateway export [--format gateway|mcpServers] [--secrets] [--out <file>]
mcp-gateway hash-token <token>                                                     # sha256 for settings.auth.adminTokenHash
mcp-gateway connect <url> [--api-key K] [--header 'Name: v'] [--sse]              # stdio ⇄ HTTP bridge
mcp-gateway-connect <url> …                                                        # same bridge as a standalone package (@mcp-gateway/connect)

환경 변수: GATEWAY_HOST, GATEWAY_PORT, GATEWAY_DATA_DIR, GATEWAY_CONFIG, GATEWAY_ADMIN_TOKEN, GATEWAY_PUBLIC_URL, GATEWAY_LOG_LEVEL, GATEWAY_REQUIRE_API_KEY, GATEWAY_WEB_DIR, GATEWAY_SEED_CONFIG (Docker). 우선순위: CLI 플래그 > 환경 변수 > config.json > 기본값.

엔드포인트

요청/응답 형식을 포함한 전체 라우트 목록은 docs/SPEC.md §7에 있습니다.

보안 참고 사항

• 관리자 토큰이 없으면 GUI/API가 열려 있습니다: 기본 루프백 바인드를 유지하거나 GATEWAY_ADMIN_TOKEN을 설정하세요.

• /mcp를 localhost 밖으로 노출하기 전에 API 키 필요를 켜세요. 키는 각 에이전트가 필요한 서버/그룹으로 범위를 지정하세요.

• 비밀 값: 리터럴 값보다 ${VAR} 참조를 사용하세요. 비밀처럼 보이는 키 아래의 값은 API 응답과 내보내기에서 삭제됩니다(?secrets=1 / 비밀 값 포함 내보내기에는 포함됩니다).

• 인터넷에 노출되는 모든 것 앞에 TLS 종료 리버스 프록시를 두세요(Anthropic API MCP 커넥터에 필요).

• 게이트웨이는 사용자가 구성한 명령을 실행합니다 — 관리자 액세스 권한이 있는 사람은 호스트에서 임의의 프로세스를 실행할 수 있습니다.

개발

npm run dev          # gateway (tsx watch) + Vite dev server
npm run typecheck    # all workspaces
npm test             # vitest: shared unit tests, server integration tests (real stdio/HTTP fixtures), bridge tests
npm run build        # server bundle (esbuild), connect bundle, web (vite)

구조: packages/shared(zod 구성 스키마, DTO, 템플릿, 네이밍 헬퍼 — 브라우저 안전), packages/server(Express 5 + @modelcontextprotocol/sdk: 업스트림 관리자, 프록시 서버, 세션, REST/MCP 라우트, CLI), packages/web(React 19 + Vite), packages/connect(stdio 브리지), examples/postgres-scenario(docker-compose 데모).

제한 사항 / 로드맵

• 업스트림 서버에 대한 OAuth는 구현되어 있지 않습니다(bearer/basic/header 인증 사용). 다운스트림 클라이언트 용 OAuth도 구현되어 있지 않습니다(대신 API 키 사용).

• 리소스는 그룹에서 네임스페이스되지 않습니다 — URI는 소유 서버로 라우팅되며, 멤버 간에 동일한 URI는 첫 번째 멤버로 해석됩니다.

• 속도 제한이 없습니다. 필요하다면 앞에 리버스 프록시를 두세요.

• 단일 프로세스, 인메모리 세션 및 로그(재시작 시 세션이 사라지며 클라이언트는 다시 초기화합니다).

라이선스

Apache License 2.0 — LICENSE 및 NOTICE를 참조하세요.