mcp-proxy

MCP Proxy is a central hub that connects to multiple backend MCP servers (stdio, SSE, and HTTP) and exposes their combined capabilities through a unified SSE interface, a Streamable HTTP interface, or as a standalone Stdio-based MCP server. It discovers and aggregates tools and resources from all active backend servers and routes tool calls and resource requests to the appropriate backend. The proxy also supports an optional Web UI for managing server connections and tool configurations, with live-reload capabilities so changes take effect without restarting the proxy.

To use the proxy, configure your backend MCP servers in config/mcp_server.json and start the proxy. The proxy will connect to each backend based on its type (stdio, sse, or http) and will expose a consolidated /sse endpoint for real-time events and a /mcp endpoint for streaming/mcp interactions. If you enable the Admin UI, you can adjust server entries, enable or disable specific tools, and trigger installation tasks for stdio backends. Authentication can be applied per-backend via API keys or Bearer tokens, and the proxy supports multiple concurrent SSE client connections.

Prerequisites:

• Node.js 14+ or an appropriate runtime if required by your build (per MCP server documentation)
• Access to the project repository and permission to install dependencies
• Configured backend MCP servers listed in config/mcp_server.json

Installation steps:

1. Clone the repository and install dependencies

git clone https://github.com/your-org/mcp-proxy.git
cd mcp-proxy
npm install

2. Create and review configuration

• Ensure config/mcp_server.json exists and contains your backend server definitions (stdio, sse, or http).
• Example structure is shown in the repository README.

3. Configure environment

• Set any required environment variables (e.g., API keys, tokens) in your shell or a .env file as supported by the deployment method.
• Example:

export ENABLE_ADMIN_UI=true
export TOOLS_FOLDER=/opt/tools

4. Run the proxy

# If using Node-based runtime (example)
npm run start

5. Optional: Access the Admin UI

• If ENABLE_ADMIN_UI is true, open your browser to http://localhost:PORT/admin (adjust PORT as configured) to manage servers and tools.

• The proxy aggregates tools and resources from all active backend MCP servers. If multiple backends expose the same tool, governance in the Admin UI determines which tool instance is presented to clients.
• For stdio backends, installation commands run from the parent directory of the target installation path. Use with caution to avoid executing arbitrary commands.
• When using HTTP or SSE backends, provide either an API key or a Bearer token for authentication per backend. Bearer tokens take precedence when both are provided for a given backend.
• The Web UI is optional and requires enabling (ENABLE_ADMIN_UI). It provides live reloading of server and tool configurations without needing to restart the proxy.
• Ensure the user running the proxy has write permissions to the installation directories used by stdio backends.