Portcall

로컬 MCP 서버를 HTTP로 서빙하는 소형 플러그인 게이트웨이입니다.

이름은 해상 용어의 말장난입니다: port call — port(항구 / 네트워크 포트) + call (선박의 기항 / 요청).

무엇인가

Portcall은 하나의 HTTP 포트에서 수신 대기하며 하나 이상의 MCP 서버를 개별 경로에 마운트합니다:

/vault/mcp   → mcpvault (Obsidian vault)
/healthz     → liveness + mount list

각 마운트는 독립적인 MCP 엔드포인트입니다. 클라이언트는 이를 개별적으로 등록합니다 — 도구 집계가 없으므로 이름 충돌도, 유지 관리할 네임스페이싱 체계도 없습니다.

포트를 localhost 밖으로 노출하는 것은 의도적으로 범위 밖입니다. 터널, 리버스 프록시, 또는 아무것도 앞에 두지 마세요; Portcall은 기본적으로 127.0.0.1에 바인딩하며 업스트림에 무엇이 있는지 신경 쓰지 않습니다.

Related MCP server: mcp-unify

왜 stdio 브리지가 아닌가

stdio MCP 서버를 HTTP에 올리는 가장 확실한 방법은 supergateway와 같은 범용 브리지입니다. 작동은 하지만 구조적 문제가 있습니다: 모든 요청이나 세션이 자식 프로세스를 생성하며, 그 자식 프로세스를 회수하는 것은 잘못 구현하기 쉽습니다.

특히 supergateway에서는 자식 프로세스가 transport.onclose 또는 transport.onerror에서만 회수됩니다. 정상적으로 완료된 무상태 요청에서 transport.close()를 호출하는 곳이 없으므로 onclose는 절대 발생하지 않으며 성공한 모든 요청이 프로세스를 누수시킵니다 — 실패한 요청만 정리됩니다. 상태 저장 모드는 누수되지 않지만(세션 타이머가 트랜스포트를 닫음), 대신 장기 유지 GET SSE 스트림을 보유하므로 일부 프록시가 제대로 처리하지 못합니다.

명령을 npx로 감싸면 더 나빠집니다: npx는 실제 서버를 포크하므로 자식을 죽이면 래퍼가 죽고 손자 프로세스는 고아가 됩니다.

Portcall의 답은 필요하지 않을 때 아무것도 생성하지 않는 것입니다.

어댑터

inProcess가 흥미로운 경우이며 자체 호스팅할 가치가 있는 서버를 포함합니다. 예를 들어 @bitbonsai/mcpvault는 MCP SDK v2 Server를 반환하는 createServer(vaultPath, options)를 내보냅니다; 그 bin 엔트리는 본질적으로 serveStdio(() => createServer(...))입니다. Portcall은 동일한 함수를 직접 호출하고 stdio를 완전히 건너뜁니다.

SDK는 요청마다 새 서버 인스턴스를 생성하고 요청과 함께 폐기하므로, 타임아웃할 세션 상태도 누적되는 핸들도 없습니다.

프로토콜 버전

Portcall은 @modelcontextprotocol/server v2를 기반으로 하며, 단일 핸들러에서 두 프로토콜 시대를 서빙합니다:

• 최신 (2026-07-28) — 요청별 엔벨로프. 요청은 MCP-Protocol-Version, Mcp-Method, (도구 호출의 경우) Mcp-Name 헤더와 params._meta 블록을 전달합니다. initialize 핸드셰이크도 장기 유지 세션도 없습니다; 발견은 server/discover입니다.

• 레거시 (2025년대) — 기본적으로 무상태로 서빙됩니다. GET 및 DELETE (2025 세션 작업)는 405로 응답합니다. PORTCALL_MODERN_ONLY=true를 설정하면 레거시 트래픽을 완전히 거부합니다.

최신 시대는 요청별이므로 유지할 상시 SSE 스트림이 없습니다. 이는 프록시 문제 한 부류를 우회합니다: 일부 리버스 프록시는 첫 본문 바이트가 도착할 때까지 응답 헤더를 보류하는데, 이는 막 열렸지만 조용한 SSE 스트림을 무기한 지연시킵니다. 발생하는 스트림에 대해서는 PORTCALL_KEEPALIVE_MS가 SSE 주석 프레임 간격을 제어합니다; 앞에 있는 프록시가 버퍼링한다면 값을 낮추세요.

구성

모든 호스트별 값은 환경 변수에서 옵니다.

PORTCALL_TOKEN은 모든 마운트를 Authorization: Bearer <token>으로 게이트합니다. 일부 MCP 클라이언트 — 그중 Claude의 커스텀 커넥터 UI — 는 요청 헤더를 설정할 방법이 없으므로, 그러한 클라이언트의 경우 토큰을 대신 업스트림에서 강제해야 합니다(또는 네트워크 계층에서 접근을 제어한 채 생략).

PORTCALL_PATH_PREFIX는 바로 그러한 클라이언트를 위한 대비책입니다: 모든 마운트를 선택한 세그먼트 아래로 이동시켜 /vault/mcp가 /<prefix>/vault/mcp가 되고 URL 자체가 비밀을 담게 됩니다. 그로부터 두 가지가 따라오며 서버는 둘 다 강제합니다:

• 404 응답은 not_found만 말합니다. 무엇이 마운트되어 있는지 절대 나열하지 않습니다.

• 마운트 목록은 공개 /healthz에서 /<prefix>/healthz로 이동합니다. 기본 /healthz는 여전히 응답하므로 활성 프로브는 계속 작동하지만 경로는 공개하지 않습니다.

경로 접두사를 헤더보다 약한 것으로 취급하세요. URL은 프록시 접근 로그, 크래시 보고서, 목적지를 기록하는 모든 것에 도달하며, 유출된 하나는 유출된 토큰과 동일한 접근 권한을 부여합니다. 기준을 높일 뿐 — 인증이 아닙니다.

어떤 플러그인이 어디에 마운트되는지는 plugins.config.ts에 선언됩니다.

실행

Node 24 필요 (.nvmrc 참조).

npm install
npm run build
cp .env.example .env    # then set PORTCALL_VAULT_PATH
npm start

npm start와 npm run dev 모두 .env가 있으면 로드하고 없으면 없이 시작하므로, 데몬이 대신 환경을 직접 주입할 수 있습니다. 이미 환경에 설정된 변수는 덮어쓰지 않습니다.

npm run dev는 엔트리 포인트를 tsx로 watch 모드로 실행합니다. 데몬은 빌드된 출력물을 실행해야 하며 tsx가 아닙니다.

가동 중인지 확인:

curl -s localhost:7100/healthz

테스트

npm test        # builds, then runs unit and integration tests
npm run typecheck

테스트 의존성 없음: 러너는 node:test이고, tsx(npm run dev에 이미 필요)가 TypeScript를 로드합니다.

통합 테스트는 블랙박스입니다. 임시 볼트와 임시 포트에 빌드된 서버를 띄우고 실제 HTTP로 구동하므로, 데몬이 실행하는 것과 동일한 산출물을 검증합니다 — 라우팅, /mcp 별칭, 베어러 인증, 두 프로토콜 시대 모두. 단위 테스트는 마운트 해석과 베어러 검사를 다루는데, 여기서 조용한 회귀는 오류가 아닌 죽은 클라이언트로 보일 수 있습니다.

구조

src/
  server.ts            HTTP entry point, wiring, health, shutdown
  routes.ts            mount resolution and URL normalisation
  auth.ts              bearer token check
  config.ts            environment parsing
  log.ts               structured logging
  types.ts             the Plugin interface
  adapters/
    inProcess.ts       library-factory adapter
  plugins/
    vault.ts           mcpvault
plugins.config.ts      which plugins mount at which paths
test/
  integration.test.ts  black-box tests against the built server
  routes.test.ts       mount resolution
  auth.test.ts         bearer token check
  helpers.ts           server harness and MCP request builders

라이선스

MIT