mcp-proxy MCP — Cas d'usage, Installer & Démo en direct

Name: mcp-proxy MCP Server
Author: tbxark

Pourquoi l'utiliser

Fonctionnalités clés

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

Démo en direct

Aperçu en pratique

proxy-2.replay ▶ prêt

0/0

Installer

Choisissez votre 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
    }
  }
}

Ouvrez Claude Desktop → Settings → Developer → Edit Config. Redémarrez après avoir enregistré.

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

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

Cursor utilise le même schéma mcpServers que Claude Desktop. La config projet l'emporte sur la globale.

VS Code → Cline → MCP Servers → Edit

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

Cliquez sur l'icône MCP Servers dans la barre latérale Cline, puis "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

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

Même format que Claude Desktop. Redémarrez Windsurf pour appliquer.

~/.continue/config.json

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

Continue utilise un tableau d'objets serveur plutôt qu'une map.

~/.config/zed/settings.json

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

Ajoutez dans context_servers. Zed recharge à chaud à la sauvegarde.

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

Une seule ligne. Vérifiez avec claude mcp list. Supprimez avec claude mcp remove.

Cas d'usage

Usages concrets : 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

Quand l'utiliser : 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.

Prérequis

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

Déroulement

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.✓ Copié

→ 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.✓ Copié

→ 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.✓ Copié

→ Any teammate gets all upstream tools in one step

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

Pièges

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

Combiner avec : 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

Quand l'utiliser : Your client only speaks HTTP/SSE but the MCP you need is stdio-only.

Déroulement

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.✓ Copié

→ 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.✓ Copié

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

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

→ Tools appear in the remote IDE

Résultat : A stdio-only MCP reachable from any HTTP-capable client.

Pièges

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

Combiner avec : filesystem

Upgrade an MCP for the whole team without touching client configs

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

Quand l'utiliser : A security-fix version of an upstream MCP drops and you need everyone on it today.

Déroulement

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.✓ Copié

→ 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.✓ Copié

→ Tool list unchanged from consumer perspective

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

Pièges

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

Combinaisons

Associez-le à d'autres MCPs pour un effet X10

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.✓ Copié

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.✓ Copié

Outils

Ce que ce MCP expose

Outil	Entrées	Quand appeler	Coût
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

Coût et limites

Coût d'exécution

Quota d'API: No own quota; passes through upstream server limits
Tokens par appel: Negligible overhead beyond the upstream response
Monétaire: Free, MIT licensed
Astuce: Run on a tiny box — 512MB RAM handles dozens of upstreams. Real cost is upstream API fees.

Sécurité

Permissions, secrets, portée

Stockage des identifiants : Upstream credentials in host env vars or config.json; keep config.json out of git

Sortie de données : Proxy forwards to whichever upstream servers you configure; no telemetry back to tbxark

Ne jamais accorder : 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.

Dépannage

Erreurs courantes et correctifs

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.

Vérifier : 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.

Vérifier : 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.

Vérifier : nginx/Caddy log shows client timeout

Docker container exits immediately

Config JSON invalid. Validate with jq before starting.

Vérifier : docker logs shows JSON parse error

Alternatives

mcp-proxy vs autres

Alternative	Quand l'utiliser	Compromis
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

Plus

Ressources

📖 Lire le README officiel sur GitHub

🐙 Voir les issues ouvertes

🔍 Parcourir les 400+ serveurs MCP et Skills