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

Name: mcp-proxy MCP Server
Author: tbxark

왜 쓰나요

핵심 기능

Transport bridging: wrap stdio servers as HTTP/SSE so remote clients can reach them
Single config file lists all upstream servers — hot-swap without restarting clients
Docker image ghcr.io/tbxark/mcp-proxy for one-command deploy
Web-based config converter at tbxark.github.io/mcp-proxy
Namespaced tools — avoids collisions when two upstreams expose the same tool name

라이브 데모

실제 사용 모습

proxy-2.replay ▶ 준비됨

0/0

설치

클라이언트 선택

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

{
  "mcpServers": {
    "proxy-2": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/tbxark/mcp-proxy"
      ],
      "_inferred": true
    }
  }
}

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

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

{
  "mcpServers": {
    "proxy-2": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/tbxark/mcp-proxy"
      ],
      "_inferred": true
    }
  }
}

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

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "proxy-2": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/tbxark/mcp-proxy"
      ],
      "_inferred": true
    }
  }
}

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

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "proxy-2": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/tbxark/mcp-proxy"
      ],
      "_inferred": true
    }
  }
}

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

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "proxy-2",
      "command": "TODO",
      "args": [
        "See README: https://github.com/tbxark/mcp-proxy"
      ]
    }
  ]
}

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

~/.config/zed/settings.json

{
  "context_servers": {
    "proxy-2": {
      "command": {
        "path": "TODO",
        "args": [
          "See README: https://github.com/tbxark/mcp-proxy"
        ]
      }
    }
  }
}

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

claude mcp add proxy-2 -- TODO 'See README: https://github.com/tbxark/mcp-proxy'

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

사용 사례

실전 활용법: mcp-proxy

How to run a shared MCP gateway for your team

👤 Platform/DevEx engineers tired of onboarding each teammate to 10 MCPs ⏱ ~30 min intermediate

언제 쓸까: You've found 5+ MCPs that everyone on the team should use, and re-explaining the stdio config to each hire is eating your week.

사전 조건

A VM or container host reachable by every team member — Any small EC2/Fly/Hetzner box; 512MB RAM is plenty
Docker installed on that host — curl -fsSL https://get.docker.com | sh

흐름

Write a config.json listing every upstream MCP the team needs

Draft a mcp-proxy config.json that aggregates github, sentry, postgres (read-only replica), and filesystem (scoped to /data). Give each a unique namespace.✓ 복사됨

→ Valid config with namespaced server entries
Run mcp-proxy in Docker on the shared host

Write the docker run command to launch ghcr.io/tbxark/mcp-proxy on port 9090 mounting config.json, with restart=always and a healthcheck.✓ 복사됨

→ Container stays up; /health returns 200
Give teammates one URL to paste into every client

Write a 5-line onboarding snippet teammates paste into Claude Desktop's config to point at our shared proxy URL.✓ 복사됨

→ Any teammate gets all upstream tools in one step

결과: New hires reach full MCP parity in 2 minutes by pasting one URL; upgrades happen in one place.

함정

Putting the proxy on the public internet without auth — Terminate TLS and auth at a reverse proxy (Caddy/nginx/Cloudflare) in front — mcp-proxy has no auth layer
Upstream tool names collide (two servers both expose get_issue) — Use namespacing so clients see github.get_issue vs gitlab.get_issue

함께 쓰기: github · sentry · postgres

Expose a local stdio MCP to a remote IDE via HTTP

👤 Developers using a cloud IDE that can't spawn stdio processes ⏱ ~15 min beginner

언제 쓸까: Your client only speaks HTTP/SSE but the MCP you need is stdio-only.

흐름

Run mcp-proxy locally wrapping the stdio server

Generate an mcp-proxy config that wraps npx -y @modelcontextprotocol/server-filesystem /tmp as an SSE endpoint on :9090.✓ 복사됨

→ curl http://localhost:9090 returns MCP metadata
Tunnel the port to a public URL

Give me a one-liner with cloudflared or ngrok to expose :9090.✓ 복사됨

→ Public HTTPS URL
Point the remote IDE at the SSE URL

Write the IDE config entry to consume this as an SSE MCP server.✓ 복사됨

→ Tools appear in the remote IDE

결과: A stdio-only MCP reachable from any HTTP-capable client.

함정

Public tunnels are open to the world while live — Use cloudflared with Access policies or add a shared-secret header

함께 쓰기: filesystem

Upgrade an MCP for the whole team without touching client configs

👤 Team leads rolling out MCP version bumps ⏱ ~10 min beginner

언제 쓸까: A security-fix version of an upstream MCP drops and you need everyone on it today.

흐름

Bump the version in the central mcp-proxy config

Update my mcp-proxy config to pin github-mcp-server to v0.4.2 and reload.✓ 복사됨

→ New version live on the proxy
Verify tools still respond

Hit the proxy's list_tools and confirm github.* tools are present with the new server version.✓ 복사됨

→ Tool list unchanged from consumer perspective

결과: Silent upgrade — teammates pick up the new version on next tool call, no client restart needed.

함정

New version renamed a tool and broke downstream prompts — Read the upstream changelog before pinning; keep previous version configured briefly for overlap

조합

다른 MCP와 조합해 10배 효율

proxy-2 + github + sentry

Put both behind one proxy so teammates don't juggle two tokens in two configs

Configure mcp-proxy to front both github and sentry MCP servers, loading credentials from a single .env file the host reads.✓ 복사됨

proxy-2 + agent

Compare vs 1mcp-app/agent — both aggregate, different tradeoffs (Go vs Node, OAuth vs none)

Set up mcp-proxy alongside 1mcp-app/agent on the same host and benchmark tool-call latency through each.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
list_tools	(none)	Client-side — proxy handles automatically on MCP handshake	free
call_tool	name: str (optionally namespaced), args: object	Any tool invocation — proxy routes by name/namespace	1 upstream call

비용 및 제한

운영 비용

API 쿼터: No own quota; passes through upstream server limits
호출당 토큰: Negligible overhead beyond the upstream response
금액: Free, MIT licensed
팁: Run on a tiny box — 512MB RAM handles dozens of upstreams. Real cost is upstream API fees.

보안

권한, 시크릿, 파급범위

자격 증명 저장: Upstream credentials in host env vars or config.json; keep config.json out of git

데이터 외부 송신: Proxy forwards to whichever upstream servers you configure; no telemetry back to tbxark

절대 부여 금지: Exposing the proxy to the public internet without an auth layer in front

No built-in authentication — pair with reverse proxy auth (Caddy, nginx, Cloudflare Access) before exposing publicly.
Treat config.json like a secrets file; it contains tokens for every upstream.

문제 해결

자주 발생하는 오류와 해결

Upstream server failed to start

Check the command path in config.json is absolute or on the container PATH. docker exec in and run manually.

확인: docker logs <proxy-container>

Tool call returns 'tool not found' but list_tools shows it

Namespace mismatch — with namespacing on, clients must call server.tool_name, not tool_name.

확인: curl http://proxy:9090/tools | jq

SSE connection drops every 30s

Reverse proxy idle timeout too short. Raise to 5 min or disable buffering for /sse paths.

확인: nginx/Caddy log shows client timeout

Docker container exits immediately

Config JSON invalid. Validate with jq before starting.

확인: docker logs shows JSON parse error

대안

mcp-proxy 다른 것과 비교

대안	언제 쓰나	단점/장점
1mcp-app/agent	You want OAuth 2.1 and scope-based auth built in	Heavier footprint, Node-based vs Go
Hyprmcp Jetski	You need analytics and prompt-level visibility on top of aggregation	Requires Kubernetes/PostgreSQL — overkill for small teams
Direct client-side configs	Team is 1-3 people and you rarely change servers	Zero infra, but every change is N updates

mcp-proxy