mcphub MCP — 사용 사례, 설치 & 라이브 데모

왜 쓰나요

핵심 기능

그룹별(/mcp/{group})과 서버별(/mcp/{server}) 라우팅이 지원되는 통합 /mcp 엔드포인트
스마트 라우터($smart)는 벡터 의미 검색을 사용하여 모든 서버에서 툴을 선택합니다
핫스왑 설정 — 재시작 없이 서버 추가/제거 가능
OAuth 2.0 (클라이언트 + 서버), GitHub/Google 소셜 로그인
프로덕션용 Postgres 백엔드, 로컬용 SQLite

라이브 데모

실제 사용 모습

mcphub.replay ▶ 준비됨

0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcphub": {
      "command": "npx",
      "args": [
        "-y",
        "mcphub"
      ],
      "_inferred": true
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "mcphub": {
      "command": "npx",
      "args": [
        "-y",
        "mcphub"
      ],
      "_inferred": true
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "mcphub": {
      "command": "npx",
      "args": [
        "-y",
        "mcphub"
      ],
      "_inferred": true
    }
  }
}

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcphub": {
      "command": "npx",
      "args": [
        "-y",
        "mcphub"
      ],
      "_inferred": true
    }
  }
}

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "mcphub",
      "command": "npx",
      "args": [
        "-y",
        "mcphub"
      ]
    }
  ]
}

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

{
  "context_servers": {
    "mcphub": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "mcphub"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add mcphub -- npx -y mcphub

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: mcphub

팀을 위해 20개의 MCP 서버를 하나의 URL을 통해 노출하는 방법

👤 플랫폼 엔지니어, 팀 리더 ⏱ ~30 min intermediate

언제 쓸까: 엔지니어들이 계속해서 로컬 설정을 복사-붙여넣기하고 서로의 설정을 깨뜨립니다.

사전 조건

Docker와 DNS 이름이 있는 서버 — 저렴한 VPS를 사용할 수 있으며, TLS는 Caddy 또는 nginx를 사용합니다
서버를 나열한 mcp_settings.json — MCPHub 샘플에서 시작하여 MCP당 하나의 항목을 추가합니다

흐름

허브 배포

실행: docker run -p 3000:3000 -v $PWD/mcp_settings.json:/app/mcp_settings.json samanhappy/mcphub✓ 복사됨

→ 로그의 관리자 로그인 URL + 생성된 비밀번호
그룹 생성

관리자 UI에서 'dev'(github, filesystem, postgres)와 'data'(postgres, bigquery) 그룹을 생성합니다.✓ 복사됨

→ /mcp/dev와 /mcp/data에서 그룹이 표시됩니다
URL 배포

팀과 https://mcp.yourco.internal/mcp/dev를 공유하면, 팀원들이 이를 클라이언트에서 하나의 HTTP MCP로 추가합니다.✓ 복사됨

→ 팀원들이 하나의 설정 라인으로 연결합니다

결과: 하나의 작동 가능한 엔드포인트가 20개의 머신별 설정을 대체합니다.

함정

Docker 로그에서 관리자 비밀번호 노출 — ADMIN_PASSWORD 환경변수를 명시적으로 설정하고, 첫 로그인 시 로테이션합니다
허브를 공개 인터넷에 노출 — VPN 뒤에 배치하거나 사용자별 베어러 토큰을 요구합니다

$smart가 프롬프트에 적합한 MCP를 자동으로 선택하도록 하는 방법

👤 단일 컨텍스트에 맞지 않을 정도로 많은 도구를 실행하는 팀 ⏱ ~15 min advanced

언제 쓸까: MCP에 걸쳐 200개 이상의 툴이 있고 모델의 툴 예산을 초과합니다.

흐름

$smart 엔드포인트 활성화

클라이언트를 특정 서버 대신 https://hub.example.com/mcp/$smart로 지정합니다.✓ 복사됨

→ 의도에 따라 라우팅하는 단일 메타 툴이 노출됩니다
자연스럽게 프롬프트 작성

github.com/org/repo에서 나를 기다리는 PR을 찾아 캘린더에 30분 리뷰 슬롯으로 추가합니다.✓ 복사됨

→ 허브가 백그라운드에서 github + google-calendar 툴을 선택합니다

결과: 컨텍스트의 툴은 줄어들지만 동일한 기능을 제공합니다.

함정

스마트 라우터가 모호한 프롬프트에서 잘못된 MCP를 선택합니다 — 그룹별 엔드포인트를 폴백으로 사용 가능하게 유지합니다

다운타임 없이 허브에 새로운 MCP 서버를 추가하는 방법

👤 운영자 ⏱ ~5 min beginner

언제 쓸까: 새로운 MCP가 출시되었고 모두를 강제 종료하지 않고 오늘 라이브에 올리고 싶습니다.

흐름

UI를 통해 mcp_settings.json 편집

MCPHub 대시보드에서 새로운 서버 항목을 추가하고 저장합니다.✓ 복사됨

→ 핫 리로드 알림, 새로운 툴이 나타납니다
그룹에 할당

새 서버를 'data' 그룹에 추가합니다.✓ 복사됨

→ /mcp/data에 새로운 툴이 포함됩니다

결과: 새로운 MCP가 1분 이내에 온라인이 되며, 클라이언트 재연결이 필요하지 않습니다.

조합

다른 MCP와 조합해 10배 효율

mcphub + toolhive

ToolHive를 사용하여 개별 MCP를 컨테이너화하고, MCPHub로 라우팅합니다

ToolHive로 실행되는 github MCP를 MCPHub에 'dev' 그룹 아래에 등록합니다.✓ 복사됨

mcphub + proxy

허브용 stdio 전용 MCP를 HTTP를 통해 노출합니다

mcp-proxy를 사용하여 로컬 stdio MCP를 HTTP로 연결하여 MCPHub이 마운트할 수 있도록 합니다.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
(meta) route-by-group	HTTP 경로 /mcp/{group}	정기적 사용 — 영향 범위를 좁히기 위한 용도	무료
(meta) route-by-server	/mcp/{server}	정확히 하나의 서버의 표면을 원할 때	무료
(meta) $smart semantic router	/mcp/$smart	컨텍스트에 넣기에 너무 많은 툴이 있을 때	호출당 1개의 벡터 검색

비용 및 제한

운영 비용

API 쿼터: 허브에서 강제하는 할당량 없음; 다운스트림 MCP는 자신의 할당량을 유지합니다
호출당 토큰: 도구 메타데이터 오버헤드 약 50개 토큰 추가
금액: 무료 (오픈소스, Apache 2.0)
팁: 결정론적 동작과 추가 벡터 검색 비용 없음을 위해 $smart 대신 그룹 경로를 사용합니다.

보안

권한, 시크릿, 파급범위

최소 스코프: 사용자당 베어러 토큰 신뢰할 수 있는 클라이언트에 대한 네트워크 수준 제한

자격 증명 저장: ADMIN_PASSWORD 환경변수; 다운스트림 MCP 시크릿은 mcp_settings.json 또는 시크릿 관리자를 통해

데이터 외부 송신: 허브는 프록시일 뿐 — 데이터는 각 다운스트림 MCP가 보내는 곳으로 전달됩니다

절대 부여 금지: 인증 없이 공개 노출 공개 인터넷의 관리자 UI

자격증명이 포함된 경우 mcp_settings.json을 git에 체크인하지 마십시오 — 볼륨으로 마운트하십시오.

문제 해결

자주 발생하는 오류와 해결

로그인할 수 없음 / 비밀번호 알 수 없음

첫 부팅 시 컨테이너 로그에서 생성된 비밀번호를 확인하거나 ADMIN_PASSWORD를 설정합니다.

확인: docker logs mcphub | grep -i password

새 MCP가 표시되지만 툴이 없습니다

다운스트림 MCP가 시작하지 못했을 가능성이 높습니다. 서버 카드의 '로그'를 클릭합니다.

스마트 라우터가 '일치하는 툴 없음'을 반환합니다

Settings > Index tools에서 벡터 저장소를 다시 인덱싱합니다.

OAuth 리디렉션 불일치

OAuth 공급자에서 정확한 콜백 URL을 등록합니다(허브의 공개 URL과 일치해야 함).

대안

mcphub 다른 것과 비교

대안	언제 쓰나	단점/장점
Unla (MCP Gateway)	YAML 기반 REST-to-MCP 변환과 멀티테넌트가 필요한 경우	Go 기반이며 다른 운영자 모델입니다
ToolHive	MCP당 컨테이너 수준의 격리가 필요한 경우	MCP 실행에 중점을 두고 라우팅/집계에는 덜 중점을 둡니다
mcp-proxy	멀티 서버 집계가 아닌 전송 브리징만 필요한 경우	단일 서버; UI 없음

mcphub