MCP Proxy
Author: sparfenyuk
Description: A Python CLI proxy/bridge for Model Context Protocol (MCP) servers that lets you switch transports between (1) stdio SSE/StreamableHTTP (connect Claude Desktop/stdio clients to remote SSE/StreamableHTTP servers) and (2) SSE stdio (expose a local stdio MCP server over an SSE endpoint). Supports optional auth headers, OAuth2 client credentials, SSL verify controls, CORS, named backend servers via CLI or JSON config, and a published container image.
Stars: 2.4k
Forks: 221
License: MIT License
Category: Open Source
Overview
Installation
# Option 1: With uv (recommended)
uv tool install mcp-proxy
# Option 2: With pipx (alternative)
pipx install mcp-proxyuv tool install git+https://github.com/sparfenyuk/mcp-proxy- Uninstall:```bash
uv tool uninstall mcp-proxydocker run --rm -t ghcr.io/sparfenyuk/mcp-proxy:v0.3.2-alpine --helpFAQs
What are the most common issues faced when setting up an MCP server?
The most common MCP server setup issues include transport mismatches between clients and servers, PATH resolution errors causing ENOENT failures in Claude Desktop, missing separator arguments that break child-process spawning, authentication header configuration gaps, and container base images lacking required binaries like uv for uvx-based servers.
How can I optimize the performance of an MCP server?
Optimize MCP server performance by selecting deployment models matched to workload patterns: local hosting for low-latency iteration, remote HTTP for centralized scaling, or gateways for orchestration. Enable autoscaling, batching, GPU fractioning, and model quantization to boost throughput and reduce memory. Monitor latency, GPU utilization, and costs; enforce rate limiting and versioning rollouts to balance reliability with cost.
What are the best practices for securing an MCP server?
Best practices include enforcing Bearer token or OAuth2 authentication with short-lived tokens, enabling TLS for encrypted transport, implementing CORS policies to restrict client origins, using least-privilege service accounts, logging all connection attempts for audit trails, and isolating proxy instances per environment. Deploy MCP Proxy behind reverse proxies with rate limiting to mitigate denial-of-service risks.
How do I troubleshoot connectivity issues on an MCP server?
Start with network and config validation: ping the server URL and verify the JSON config matches the provider's exact format, including correct ports and auth tokens. Check client logs for timeout errors (non-streaming calls default to 100 seconds), restart the AI client to reload tool definitions, and confirm Node.js version is eighteen or higher if using stdio transports.
How do I configure MCP Proxy to connect Claude Desktop to a remote SSE server with OAuth2 authentication?
Add OAuth2 flags to your Claude Desktop config alongside the standard proxy command. Include client-id, client-secret, and token-url as arguments to mcp-proxy, which will automatically handle token acquisition and refresh. The proxy translates between Claude's stdio interface and your SSE endpoint while managing the OAuth2 flow transparently, eliminating manual token management.
What is the difference between Mode 1 (stdio to SSE) and Mode 2 (SSE to stdio) in MCP Proxy, and when should I use each?
Mode 1 enables stdio-only clients like Claude Desktop to consume remote servers by translating outbound requests into SSE or HTTP. Mode 2 wraps a local stdio server inside an SSE endpoint for remote access. Use Mode 1 when your client is stdio-locked but the server is remote; Mode 2 when your stdio server needs network accessibility.