mcp-proxy MCP — Anwendungsfälle, Installieren & Live-Demo

Name: mcp-proxy MCP Server
Author: tbxark

Warum nutzen

Hauptfunktionen

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

Live-Demo

In der Praxis

proxy-2.replay ▶ bereit

0/0

Installieren

Wählen Sie Ihren Client

~/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
    }
  }
}

Öffne Claude Desktop → Settings → Developer → Edit Config. Nach dem Speichern neu starten.

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

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

Cursor nutzt das gleiche mcpServers-Schema wie Claude Desktop. Projektkonfiguration schlägt die globale.

VS Code → Cline → MCP Servers → Edit

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

Klicken Sie auf das MCP-Servers-Symbol in der Cline-Seitenleiste, dann "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

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

Gleiche Struktur wie Claude Desktop. Windsurf neu starten zum Übernehmen.

~/.continue/config.json

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

Continue nutzt ein Array von Serverobjekten statt einer Map.

~/.config/zed/settings.json

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

In context_servers hinzufügen. Zed lädt beim Speichern neu.

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

Einzeiler. Prüfen mit claude mcp list. Entfernen mit claude mcp remove.

Anwendungsfälle

Praxisnahe Nutzung: 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

Wann einsetzen: 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.

Voraussetzungen

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

Ablauf

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.✓ Kopiert

→ 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.✓ Kopiert

→ 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.✓ Kopiert

→ Any teammate gets all upstream tools in one step

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

Fallstricke

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

Kombinieren mit: 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

Wann einsetzen: Your client only speaks HTTP/SSE but the MCP you need is stdio-only.

Ablauf

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.✓ Kopiert

→ 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.✓ Kopiert

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

Write the IDE config entry to consume this as an SSE MCP server.✓ Kopiert

→ Tools appear in the remote IDE

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

Fallstricke

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

Kombinieren mit: filesystem

Upgrade an MCP for the whole team without touching client configs

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

Wann einsetzen: A security-fix version of an upstream MCP drops and you need everyone on it today.

Ablauf

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.✓ Kopiert

→ 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.✓ Kopiert

→ Tool list unchanged from consumer perspective

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

Fallstricke

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

Kombinationen

Mit anderen MCPs für 10-fache Wirkung

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.✓ Kopiert

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.✓ Kopiert

Werkzeuge

Was dieses MCP bereitstellt

Werkzeug	Eingaben	Wann aufrufen	Kosten
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

Kosten & Limits

Was der Betrieb kostet

API-Kontingent: No own quota; passes through upstream server limits
Tokens pro Aufruf: Negligible overhead beyond the upstream response
Kosten in €: Free, MIT licensed
Tipp: Run on a tiny box — 512MB RAM handles dozens of upstreams. Real cost is upstream API fees.

Sicherheit

Rechte, Secrets, Reichweite

Credential-Speicherung: Upstream credentials in host env vars or config.json; keep config.json out of git

Datenabfluss: Proxy forwards to whichever upstream servers you configure; no telemetry back to tbxark

Niemals gewähren: 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.

Fehlerbehebung

Häufige Fehler und Lösungen

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.

Prüfen: 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.

Prüfen: 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.

Prüfen: nginx/Caddy log shows client timeout

Docker container exits immediately

Config JSON invalid. Validate with jq before starting.

Prüfen: docker logs shows JSON parse error

Alternativen

mcp-proxy vs. andere

Alternative	Wann stattdessen	Kompromiss
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

Mehr

Ressourcen

📖 Offizielle README auf GitHub lesen

🐙 Offene Issues ansehen

🔍 Alle 400+ MCP-Server und Skills durchsuchen