mcp-proxy MCP — Casos de uso, Instalar & Demo ao vivo

Name: mcp-proxy MCP Server
Author: tbxark

Por que usar

Principais recursos

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

Demo ao vivo

Como fica na prática

proxy-2.replay ▶ pronto

0/0

Instalar

Escolha seu cliente

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

Abra Claude Desktop → Settings → Developer → Edit Config. Reinicie após salvar.

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

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

Cursor usa o mesmo esquema mcpServers que o Claude Desktop. Config de projeto vence a global.

VS Code → Cline → MCP Servers → Edit

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

Clique no ícone MCP Servers na barra lateral do Cline, depois "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

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

Mesmo formato do Claude Desktop. Reinicie o Windsurf para aplicar.

~/.continue/config.json

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

O Continue usa um array de objetos de servidor em vez de um map.

~/.config/zed/settings.json

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

Adicione em context_servers. Zed recarrega automaticamente ao salvar.

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

Uma linha só. Verifique com claude mcp list. Remova com claude mcp remove.

Casos de uso

Usos do mundo real: 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

Quando usar: 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é-requisitos

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

Fluxo

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

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

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

→ Any teammate gets all upstream tools in one step

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

Armadilhas

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

Combine com: 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

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

Fluxo

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

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

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

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

→ Tools appear in the remote IDE

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

Armadilhas

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

Combine com: filesystem

Upgrade an MCP for the whole team without touching client configs

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

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

Fluxo

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

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

→ Tool list unchanged from consumer perspective

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

Armadilhas

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

Combinações

Combine com outros MCPs para 10× de alavancagem

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

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

Ferramentas

O que este MCP expõe

Ferramenta	Entradas	Quando chamar	Custo
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

Custo e limites

O que custa rodar

Cota de API: No own quota; passes through upstream server limits
Tokens por chamada: Negligible overhead beyond the upstream response
Monetário: Free, MIT licensed
Dica: Run on a tiny box — 512MB RAM handles dozens of upstreams. Real cost is upstream API fees.

Segurança

Permissões, segredos, alcance

Armazenamento de credenciais: Upstream credentials in host env vars or config.json; keep config.json out of git

Saída de dados: Proxy forwards to whichever upstream servers you configure; no telemetry back to tbxark

Nunca conceda: 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.

Solução de problemas

Erros comuns e correções

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.

Verificar: 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.

Verificar: 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.

Verificar: nginx/Caddy log shows client timeout

Docker container exits immediately

Config JSON invalid. Validate with jq before starting.

Verificar: docker logs shows JSON parse error

Alternativas

mcp-proxy vs. outros

Alternativa	Quando usar	Troca
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

Mais

Recursos

📖 Leia o README oficial no GitHub

🐙 Ver issues abertas

🔍 Ver todos os 400+ servidores MCP e Skills