mcp-proxy MCP — 사용 사례, 설치 & 라이브 데모

왜 쓰나요

핵심 기능

stdio → SSE/Streamable HTTP (outbound mode)
SSE → stdio (inbound mode), multi-server
Header-based, OAuth2, or bearer token auth for remote endpoints
Docker image for containerized deployment
Simple uv/pipx install

라이브 데모

실제 사용 모습

proxy.replay ▶ 준비됨

0/0

설치

클라이언트 선택

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

{
  "mcpServers": {
    "proxy": {
      "command": "uvx",
      "args": [
        "mcp-proxy"
      ],
      "_inferred": true
    }
  }
}

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

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

{
  "mcpServers": {
    "proxy": {
      "command": "uvx",
      "args": [
        "mcp-proxy"
      ],
      "_inferred": true
    }
  }
}

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

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "proxy": {
      "command": "uvx",
      "args": [
        "mcp-proxy"
      ],
      "_inferred": true
    }
  }
}

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

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "proxy": {
      "command": "uvx",
      "args": [
        "mcp-proxy"
      ],
      "_inferred": true
    }
  }
}

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

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "proxy",
      "command": "uvx",
      "args": [
        "mcp-proxy"
      ]
    }
  ]
}

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

~/.config/zed/settings.json

{
  "context_servers": {
    "proxy": {
      "command": {
        "path": "uvx",
        "args": [
          "mcp-proxy"
        ]
      }
    }
  }
}

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

claude mcp add proxy -- uvx mcp-proxy

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

사용 사례

실전 활용법: mcp-proxy

How to use a remote SSE MCP server inside Claude Desktop

👤 Devs with a team-hosted MCP gateway ⏱ ~10 min beginner

언제 쓸까: Your team runs a gateway at https://mcp.team.internal but Claude Desktop only speaks stdio.

사전 조건

uv or pipx — brew install uv

흐름

Install mcp-proxy

Run: uv tool install mcp-proxy✓ 복사됨

→ mcp-proxy on PATH
Configure Claude Desktop

Add an MCP entry: command=mcp-proxy, args=['--headers','Authorization','Bearer $TOKEN','https://mcp.team.internal/sse'].✓ 복사됨

→ Claude Desktop connects on restart
Verify

In Claude, ask: what tools do you have?✓ 복사됨

→ Remote tools listed

결과: Remote server usable from stdio-only clients.

함정

Auth header not picked up — Use --headers syntax exactly; some clients mangle env var interpolation — expand the token yourself

함께 쓰기: mcphub

How to expose a local stdio MCP over HTTP for remote teammates

👤 Devs sharing a local tool temporarily ⏱ ~15 min intermediate

언제 쓸까: You built a custom stdio MCP and a remote colleague wants to try it.

흐름

Run proxy in inbound mode

mcp-proxy --sse-host 0.0.0.0 --sse-port 3333 --named-server my-tool 'uvx my-tool-mcp'✓ 복사됨

→ SSE endpoint at :3333/my-tool/sse
Tunnel it

Use ngrok or cloudflared to expose 3333 on a public URL.✓ 복사됨

→ Shareable URL
Teammate connects

They add the URL to their client (via mcp-proxy or directly if their client supports SSE).✓ 복사됨

→ Shared session working

결과: Ad-hoc sharing of local tools.

함정

No auth by default — Use --bearer-token or put it behind Caddy basic auth

How to serve multiple local MCPs from one proxy port

👤 Homelab tinkerers ⏱ ~15 min intermediate

언제 쓸까: You want one gateway serving github, filesystem, and postgres MCPs.

흐름

Start with multiple --named-server args

mcp-proxy --sse-port 3333 --named-server gh 'uvx mcp-server-github' --named-server fs 'uvx mcp-server-filesystem ~/src'✓ 복사됨

→ Endpoints /gh/sse and /fs/sse
Connect each in your client

Add each as a separate server in your MCP client.✓ 복사됨

→ Tools from both appear

결과: One process, many MCPs.

함정

Named servers share the proxy's resource budget — Don't put heavyweight MCPs in the same proxy as lightweight ones

함께 쓰기: mcphub

조합

다른 MCP와 조합해 10배 효율

proxy + mcphub

Use mcp-proxy to expose stdio MCPs that MCPHub can then aggregate over HTTP

Bridge my local github stdio MCP to HTTP with mcp-proxy, then register it in MCPHub's 'dev' group.✓ 복사됨

proxy + unla

Use Unla's public-facing gateway on top of mcp-proxy's last-mile stdio bridge

Bridge stdio MCPs with mcp-proxy and put Unla in front for OAuth + multi-tenancy.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
(proxy) stdio-to-sse	remote_url, headers?, bearer?	Connect stdio client to remote SSE server	free
(proxy) sse-to-stdio	named_server spec	Expose a stdio MCP over HTTP	free

비용 및 제한

운영 비용

API 쿼터: None
호출당 토큰: No measurable overhead
금액: Free (MIT)
팁: Skip proxy when your client natively supports the other transport — fewer moving parts.

보안

권한, 시크릿, 파급범위

최소 스코프: Network egress to the remote URL (outbound mode) Inbound port binding (inbound mode)

자격 증명 저장: Headers/tokens passed via CLI args or env

데이터 외부 송신: Whatever the bridged MCP does; proxy itself is transparent

절대 부여 금지: Don't expose inbound mode on 0.0.0.0 without auth Don't log tokens in shell history — use env vars

SSE connections can idle-timeout behind load balancers; tune LB idle_timeout or switch to Streamable HTTP.

문제 해결

자주 발생하는 오류와 해결

Connection closed immediately

The remote URL path is wrong — SSE endpoints typically end in /sse.

확인: curl -N <url>

CORS error in browser client

Start mcp-proxy with --allow-origin or put it behind a reverse proxy with CORS headers.

401 even with --bearer-token

The remote expects the token on a different header (e.g., X-API-Key). Use --headers to customize.

SSE drops after 60s

Load balancer idle timeout. Raise it or use Streamable HTTP.

대안

mcp-proxy 다른 것과 비교

대안	언제 쓰나	단점/장점
MCPHub	You need multi-server aggregation + routing, not just a bridge	Heavier — UI, DB, OAuth all bundled
Unla	You want REST-to-MCP conversion + gateway	Different problem space
supergateway	You prefer a JavaScript stdio-to-SSE bridge	Node dependency

mcp-proxy