supercorp-ai/supergateway

Supergateway가 하는 일

Supergateway는 서로 다른 네트워크 전송을 통해 MCP(Model‑Context‑Protocol) 서버를 노출하거나 사용할 수 있게 해주는 소형 커맨드라인 도구입니다. MCP 서버는 일반적으로 표준 입력/출력(stdio)을 통해 통신합니다. Supergateway는 다음을 수행할 수 있습니다:

로컬 stdio 기반 MCP 서버를 래핑하여 Server‑Sent Events (SSE), WebSockets, 또는 최신 Streamable HTTP 프로토콜을 통해 접근할 수 있게 합니다.
이미 SSE 또는 Streamable HTTP를 사용하는 원격 MCP 서버에 연결하고, 이를 로컬에서 stdio 프로세스로 제공합니다.
단일 HTTP 포트 뒤에서 여러 MCP 서버(로컬 명령 또는 원격 URL)를 각각 고유한 URL 경로로 결합합니다.
API‑키 인증, CORS, 헬스‑체크 엔드포인트, 사용자 지정 도구 접두사, 선택적 도구 노출과 같은 선택 기능을 추가합니다.

요컨대, 이는 개발자가 기본 서버를 다시 작성하지 않고도 MCP 기반 AI 도구를 웹 서비스, 디버깅 설정 또는 원격 디버깅 환경에 통합할 수 있게 해주는 전송 게이트웨이입니다.

누가 사용할 수 있을까

AI 도구 개발자 – stdio에서만 작동하는 MCP 서버를 브라우저나 다른 서비스에 노출하려는 경우.
운영 팀 – 방화벽 뒤에서 MCP 서버를 실행하고 SSE/WS를 통해 원격 디버깅을 위해 노출해야 하는 경우.
제품 팀 – 단일 HTTP 엔드포인트를 통해 여러 MCP 도구(예: Git 도구, 파일 시스템 도구)를 사용하는 AI 강화 애플리케이션을 구축하는 경우.
연구자 – 다가오는 2026‑07‑28 MCP 프로토콜 버전을 실험하고 상태 저장 vs. 무상태 스트림을 빠르게 테스트할 방법이 필요한 경우.

시작하는 방법

설치 – 가장 쉬운 방법은 npx를 사용하는 것입니다(영구 설치 불필요). 또는 GitHub 릴리스 페이지에서 사전 빌드된 바이너리를 다운로드할 수 있습니다. Homebrew도 포뮬러를 제공합니다.
간단한 예제 실행 – 로컬 파일 시스템 MCP 서버를 SSE로 노출:
```
npx -y supergateway \
    --stdio "npx -y @modelcontextprotocol/server-filesystem ./my-folder" \
    --port 8000 --baseUrl http://localhost:8000 \
    --ssePath /sse --messagePath /message
```
클라이언트는 이제 GET /sse로 이벤트를 수신하고 POST /message로 요청을 보낼 수 있습니다.
원격 서버 시도 – 기존 SSE 엔드포인트에 연결하여 터미널로 파이프:
```
npx -y supergateway --sse "https://example.com/mcp/sse"
```
보안 추가 – --apiKey 또는 --apiKeyFile을 사용하여 모든 클라이언트 요청에 베어러 토큰 또는 헤더를 요구합니다.
서버 결합 – servers.json 구성(Claude Desktop에서 사용하는 것과 동일한 형식)을 만들고 실행:
```
npx -y supergateway --config servers.json
```
각 항목은 /<name>/sse, /<name>/message 등으로 접근 가능해집니다.

주요 기능 한눈에 보기

기능	설명
전송 변환	stdio ↔ SSE, stdio ↔ WebSocket, stdio ↔ Streamable HTTP, 원격 SSE/HTTP ↔ 위의 모든 것.
다중 서버 지원	여러 MCP 서버가 포함된 JSON‑C 구성을 로드; 각 서버는 고유한 URL 네임스페이스를 가집니다.
인증	API 키(`--apiKey`, `--apiKeyFile`)를 요구하거나 업스트림 서버에 OAuth2 Bearer 토큰/헤더를 전달합니다.
헬스 체크	게이트웨이 자체 또는 래핑된 MCP 서버를 확인할 수 있는 자동 `/healthz` 엔드포인트.
도구 제어	도구 이름에 접두사를 붙이거나, 선택한 도구만 노출하거나, 다른 도구를 완전히 숨깁니다.
로깅	`info`, `debug`, 또는 `none` 선택; 로그 파이프라인을 위해 일반 텍스트 또는 JSON으로 출력.
CORS	`--cors`로 교차 출처 요청 활성화.
상태 저장 Streamable HTTP	HTTP 요청 간 세션 상태 유지(`--stateful`, `--sessionTimeout`).
우아한 종료	부모 프로세스가 종료되거나(`--exitWithProcess`) stdin이 닫힐 때 종료.
독립 실행 바이너리	릴리스에는 macOS, Linux, Windows용 단일 실행 파일이 포함 – Node.js 필요 없음.

제한 사항 및 주의 사항

MCP 전용 – Supergateway는 Model‑Context‑Protocol을 구현하는 서버에서만 작동합니다. 범용 HTTP‑to‑WebSocket 프록시가 아닙니다.
프로토콜 버전 관리 – 게이트웨이는 기본적으로 프로토콜 버전 2024‑11‑05를 사용하지만 --protocolVersion으로 재정의할 수 있습니다. 클라이언트는 동일한 버전을 지원하거나 폴백을 협상해야 합니다.
연결별 프로세스 – stdio→SSE/WS 모드에서는 각 클라이언트가 자체 MCP 프로세스를 생성하므로, 과부하 시 리소스 사용량이 증가할 수 있습니다.
보안 – 직접 TLS를 종료하지 않는 한(예: 역방향 프록시 뒤) API 키가 평문으로 전송됩니다. 게이트웨이는 자체적으로 TLS를 제공하지 않습니다.
작업 오케스트레이션 없음 – README에는 서버 결합 시 작업 처리가 "아직" 지원되지 않는다고 명시되어 있습니다.

빠른 참조 치트 시트

# 기본 stdio → SSE
npx -y supergateway --stdio "my-mcp" --port 8000 --ssePath /sse --messagePath /msg

# 원격 SSE → stdio (로컬 디버깅)
npx -y supergateway --sse "https://host/mcp/sse"

# stdio → Streamable HTTP (무상태)
npx -y supergateway --stdio "my-mcp" --outputTransport streamableHttp --port 8000

# stdio → Streamable HTTP (상태 저장, 60초 타임아웃)
npx -y supergateway --stdio "my-mcp" \
    --outputTransport streamableHttp --stateful \
    --sessionTimeout 60000 --port 8000

# API 키 보호 추가
npx -y supergateway ... --apiKey "SECRET"

# 구성 파일에서 여러 서버 로드
npx -y supergateway --config servers.json

다음 단계

전체 문서 읽기 – README에는 헬스 체크, 도구 접두사, 결합 서버에 대한 섹션 링크가 있습니다.
커뮤니티 참여 – 프로젝트는 질문과 아이디어를 위한 Discord 서버를 광고합니다.
MCP 탐구 – Model‑Context‑Protocol이 처음이라면 공식 MCP 사양과 예제에서 참조된 @modelcontextprotocol npm 패키지를 확인하세요.
기여 – 저장소에는 CLI, 구성 파서, 바이너리 릴리스가 포함되어 있습니다. TLS 종료, 작업 지원 또는 추가 전송에 대한 기여는 가치가 있을 것입니다.

요약

Supergateway는 일반적으로 stdio를 통해 통신하는 MCP(Model‑Context‑Protocol) 서버를 웹 친화적인 전송(SSE, WebSocket, Streamable HTTP)으로 또는 그 반대로 변환하는 CLI 도구입니다. 또한 원격 MCP 엔드포인트를 래핑하고, JSON‑C 구성을 통해 여러 서버를 결합하며, 보안, 헬스 체크, 로깅을 추가할 수 있습니다. 서버 코드를 다시 작성하지 않고 AI 도구 서버를 브라우저나 원격 디버깅에 노출하는 데 이상적입니다.

제목

Supergateway – stdio 기반 MCP AI 서버를 SSE, WebSocket 또는 Streamable‑HTTP 엔드포인트로 전환