AI 튜토리얼

Open MCP Gateway로 로컬 MCP 서비스를 위한 OpenAPI 게이트웨이 구축

Open MCP Gateway 설치, 로컬 MCP 서비스 구성, OpenAPI 호환 라우트 생성, Open WebUI 연동, 외부 플러그인 관리, 로그 모니터링 및 게이트웨이의 독립 실행형 네이티브 실행 파일 컴파일 방법을 알아보세요.

2026년 9월 20일약 12분 소요

Open MCP Gateway로 로컬 MCP 서비스를 위한 OpenAPI 게이트웨이 구축

Open MCP Gateway란 무엇인가요?

Open MCP Gateway(약칭 OMG)는 로컬에 배포된 Model Context Protocol 서비스를 OpenAPI 3.1.0을 준수하는 HTTP REST 경로로 노출하는 고성능 게이트웨이입니다. Bun 1.4와 TypeScript로 구축되었으며 Open WebUI 생태계를 대상으로 하지만, 커뮤니티 프로젝트이므로 Open WebUI 팀과는 관련이 없습니다.

이 게이트웨이는 외부 클라이언트와 하나 이상의 MCP 서비스 사이에서 작동합니다. Open WebUI와 같은 클라이언트는 HTTP 또는 HTTPS를 통해 게이트웨이와 통신하고, 게이트웨이는 하위 MCP 전송을 관리하며 해당 도구를 OpenAPI 호환 인터페이스로 변환합니다.

OMG는 네이티브 바이너리 stdio 서비스, Node 또는 Bun 스크립트 기반 stdio 파이프라인, SSE 또는 HTTP 네트워크 전송을 지원합니다. 따라서 실행 및 통신 모델이 서로 다른 MCP 서비스에 일관된 HTTP 인터페이스를 제공할 수 있습니다.

주요 기능

엄격한 OpenAPI 3.1.0 출력: 도구 입력 스키마는 requestBody.content['application/json'].schema 아래에 배치됩니다. 생성되는 operationId 값은 tool_*_post와 같은 이름을 추가하지 않고 원래 MCP 도구 이름을 유지합니다.
다중 MCP 전송: 네이티브 바이너리 stdio, 스크립트 stdio, SSE 및 HTTP 서비스를 하나의 게이트웨이에서 관리할 수 있습니다.
블루-그린 세션 풀: 서비스 세션은 AsyncMutex를 통해 핫 스왑되므로, 이미 진행 중인 요청을 중단하지 않고 구성을 업데이트할 수 있습니다.
수명 주기 관리: 게이트웨이는 관리되는 서비스에 프로토콜 래핑, 수명 주기 자동 복구 및 핫 리로딩을 제공합니다.
크로스 플랫폼 XDG 레이아웃: 구성, 애플리케이션 데이터, 런타임 상태 및 캐시 파일을 소스 저장소 외부에 보관합니다.
독립 실행형 빌드: Bun을 사용하면 런타임 종속성이 없는 네이티브 실행 파일로 게이트웨이를 컴파일할 수 있습니다.
리버스 프록시 지원: 게이트웨이는 X-Forwarded-* 헤더를 읽으므로 생성된 OpenAPI의 servers.url이 클라이언트가 확인하는 외부 주소를 반영합니다.

사전 요구 사항

소스에서 프로젝트를 실행하려면 Bun 1.4 이상이 필요합니다. 또한 등록할 MCP 서비스가 하나 이상 있어야 합니다. 해당 서비스는 로컬 네이티브 실행 파일, Bun을 통해 실행되는 JavaScript 또는 TypeScript 패키지, SSE 또는 HTTP로 제공되는 MCP 서비스일 수 있습니다.

게이트웨이 설치 및 실행

소스에서 실행

저장소를 클론하거나 다운로드하고 해당 디렉터리로 이동한 다음 종속성을 설치하고 개발 명령을 시작합니다.

bun install
bun run dev

개발 프로세스는 저장소 자체가 아니라 플랫폼의 XDG 구성 디렉터리에서 게이트웨이 구성을 읽습니다.

독립 실행형 실행 파일 빌드

네이티브 실행 파일을 만들려면 다음을 실행합니다.

bun run build

출력 파일은 Unix 계열 시스템에서는 build/mcp-gateway, Windows에서는 build/mcp-gateway.exe에 작성됩니다. 배포된 컴파일 바이너리는 별도의 Bun 런타임이 없어도 실행할 수 있습니다.

XDG 디렉터리 레이아웃 이해하기

Open MCP Gateway는 용도에 따라 파일을 분리합니다. 이를 통해 생성된 데이터, 설치된 플러그인, 로그 및 캐시가 소스 트리를 오염시키는 것을 방지합니다.

구성: XDG_CONFIG_HOME에는 기본 mcp-gateway/config.json5 파일이 들어 있습니다.
데이터: XDG_DATA_HOME에는 외부 MCP 플러그인 저장소와 해당 저장소의 package.json이 들어 있습니다.
상태: XDG_STATE_HOME에는 런타임 상태와 영구 로그가 저장됩니다.
캐시: XDG_CACHE_HOME에는 캐시된 사양 문서와 임시 런타임 데이터가 저장됩니다.

기본 구성 경로는 다음과 같습니다.

$XDG_CONFIG_HOME/mcp-gateway/config.json5

이 파일은 JSON5를 사용하므로 주석과 후행 쉼표를 지원합니다.

MCP 서비스 구성

필요한 경우 구성 디렉터리를 만든 다음 config.json5를 추가합니다. 다음 예제는 네이티브 MCP 실행 파일 하나와 패키지 기반 MCP 서비스 하나를 등록합니다.

{
    mcpServers: {
        // 네이티브 바이너리 Stdio
        codebase_memory: {
            command: "${HOME}/.local/bin/codebase-memory-mcp",
            args: [],
            env: {},
        },

        // 스크립트 Stdio
        another_mcp: {
            command: "bun",
            args: [
                "run",
                "${APP_DATA_DIR}/node_modules/<pkg>/dist/index.js",
            ],
            env: {},
        },
    },

    host: "127.0.0.1",
    port: 9090,
}

mcpServers 안의 각 키는 MCP 서비스를 식별합니다. 네이티브 바이너리의 경우 command를 실행 파일 경로로 설정합니다. 패키지 기반 서비스의 경우 command에 Bun을 사용하고 설치된 스크립트 경로를 args로 전달합니다. 서비스별 환경 변수는 env에 추가할 수 있습니다.

게이트웨이는 경로의 환경 변수 보간을 지원합니다. 변수에는 ${APP_DATA_DIR}, ${XDG_DATA_HOME}, ${HOME} 및 %USERPROFILE%이 포함됩니다. 보간을 사용하면 모든 절대 경로를 하드 코딩하지 않고도 여러 컴퓨터에서 구성을 쉽게 재사용할 수 있습니다.

서비스 식별자를 안정적으로 유지하세요. 예를 들어 codebase_memory라는 서비스는 해당 OpenAPI 문서를 가져올 때 사용하는 URL 경로에 노출됩니다.

외부 MCP 플러그인 관리

비즈니스별 MCP 패키지는 게이트웨이 저장소에 설치하지 않아야 합니다. 대신 게이트웨이의 XDG 데이터 디렉터리에서 설치하고 관리합니다.

cd "$XDG_DATA_HOME/mcp-gateway"
bun add <mcp-package-name>

설치된 패키지를 업그레이드하려면 다음을 실행합니다.

cd "$XDG_DATA_HOME/mcp-gateway"
bun update <pkg>

설치 후 스크립트의 stdio 예시에 나온 것처럼 ${APP_DATA_DIR}를 사용하여 config.json5에서 패키지 진입점을 참조합니다. 이렇게 하면 게이트웨이 종속성과 MCP 확장 종속성을 분리할 수 있습니다.

기본 사용법

게이트웨이 종속성을 설치하거나 네이티브 실행 파일을 빌드합니다.
$XDG_CONFIG_HOME/mcp-gateway/config.json5를 생성합니다.
mcpServers 아래에 하나 이상의 서비스를 추가합니다.
bun run dev로 게이트웨이를 시작하거나 컴파일된 실행 파일을 실행합니다.
구성된 서비스의 OpenAPI 문서를 가져와 외부 클라이언트에 등록합니다.

codebase_memory라는 서비스의 문서화된 OpenAPI URL 패턴은 다음과 같습니다.

http://<gateway-host>:8444/codebase_memory/openapi.json

이 예시에서 8444는 외부에서 액세스할 수 있는 포트입니다. 구성 예시의 9090처럼 게이트웨이의 내부 포트가 아니라 리버스 프록시 포트일 수도 있습니다.

Open WebUI와 통합

Caddy 또는 Nginx와 같은 리버스 프록시를 사용하면 원하는 외부 호스트, 포트, 프로토콜을 통해 게이트웨이를 노출할 수 있습니다. 적절한 X-Forwarded-* 헤더를 전달하도록 프록시를 구성합니다. Open MCP Gateway는 OpenAPI 문서를 생성할 때 이러한 헤더를 읽으므로 servers.url이 내부 리스너가 아닌 공용 주소를 가리키도록 합니다.

리버스 프록시 뒤에서 Open MCP Gateway를 시작합니다.
Open WebUI 관리 패널을 엽니다.
Functions, Tools 또는 OpenAPI 영역으로 이동합니다.
구성된 각 MCP 서비스의 OpenAPI 문서 URL을 등록합니다.
```
http://<gateway-host>:8444/codebase_memory/openapi.json
```
Open WebUI가 사양을 로드하도록 허용합니다. 그러면 생성된 OpenAPI 작업을 통해 MCP 서비스의 도구를 네이티브 도구로 사용할 수 있습니다.

작업 ID는 원래 MCP 도구 이름을 그대로 유지하므로 클라이언트에는 게이트웨이가 생성한 접미사나 접두사 없이 깔끔한 도구 식별자가 표시됩니다.

테스트 및 로그 모니터링

게이트웨이 또는 해당 구성을 변경한 후 프로젝트의 테스트 명령을 실행합니다.

bun run test

Windows에서는 저장소에서 PowerShell 테스트 스크립트도 제공합니다.

.\ps1_scripts\test-gateway.ps1

엔드 투 엔드 검증에는 상태 확인, MCP 핸드셰이크, 프록시 원본 정렬이 포함됩니다.

Unix 계열 시스템에서는 다음 명령으로 지속적으로 기록되는 게이트웨이 로그를 확인합니다.

tail -f "$XDG_STATE_HOME/mcp-gateway/logs/gateway.log"

프로세스 시작 문제, 잘못된 실행 파일 경로, MCP 핸드셰이크 실패 또는 리버스 프록시 구성 문제를 진단할 때 유용합니다.

고급 팁

이식 가능한 경로 사용

시스템별 절대 경로보다 ${HOME} 및 ${APP_DATA_DIR}와 같은 보간 경로를 우선 사용합니다. Windows에서는 적절한 경우 %USERPROFILE%을 사용할 수 있습니다. 이렇게 하면 시스템 간에 구성을 공유하기가 쉬워집니다.

플러그인을 소스 체크아웃 외부에 유지

외부 MCP 패키지는 $XDG_DATA_HOME/mcp-gateway에 설치합니다. 이렇게 하면 소스 트리를 깔끔하게 유지하고 게이트웨이와 비즈니스 확장을 독립적으로 업그레이드할 수 있습니다.

내부 주소와 외부 주소 분리

게이트웨이를 127.0.0.1에 바인딩하면 내부 리스너가 로컬로 유지됩니다. 그런 다음 리버스 프록시가 외부 TLS 엔드포인트를 제공할 수 있습니다. 생성된 OpenAPI 문서에 올바른 URL이 표시되도록 전달된 헤더에 공용 스킴, 호스트, 포트가 정확히 설명되어 있는지 확인합니다.

핫 업데이트 활용

블루-그린 세션 풀은 AsyncMutex로 전환을 보호하면서 서비스 세션을 교체합니다. 이 설계를 사용하면 이미 실행 중인 요청을 종료하지 않고 구성을 업데이트할 수 있습니다. 핫 리로딩과 수명 주기 자동 복구 기능은 수동 프로세스 관리의 필요성도 줄여 줍니다.

배포용 컴파일

대상 서버에 Bun이나 프로젝트 종속성을 설치할 필요가 없도록 하려면 bun run build를 사용합니다. 생성된 실행 파일을 필요한 XDG 구성 및 별도로 관리되는 MCP 바이너리나 패키지와 함께 배포합니다.

결론

Open MCP Gateway는 로컬 MCP 서비스와 엄격한 OpenAPI 3.1.0 라우트를 연결하는 통합 브리지를 제공합니다. 다중 전송 지원, 이식 가능한 XDG 기반 구성, 외부 플러그인 관리, 리버스 프록시 인식, 독립 실행형 빌드를 결합하여 로컬 MCP 도구를 Open WebUI 및 기타 OpenAPI 호환 클라이언트에서 사용할 수 있도록 하는 실용적인 방법을 제공합니다.