mcp-proxy

The MCP Proxy Server acts as a single HTTP entrypoint that aggregates multiple MCP servers behind it. It proxies and streamlines tools, prompts, and resources from various MCP backends, exposing them through Server-Sent Events (SSE) or streamable HTTP. This allows clients to connect once and retrieve content from multiple MCP sources in a unified interface, with flexible client type support such as stdio, SSE, and streamable-http. Set up and configure the proxy to point to the individual MCP backends you want to aggregate, and the proxy will handle routing, authentication (if configured), and streaming of data to clients.

Prerequisites:

• Docker installed (recommended for quick start) or Go toolchain if building from source
• Access to a config.json that defines the MCP backends to aggregate

Option A: Run with Docker (recommended)

1. Prepare a configuration file (config.json) that lists the MCP backends to proxy. Example content is provided in docs/configuration.md.
2. Run the container with your config mounted:

# Example using docker run with a mounted config
docker run -d -p 9090:9090 -v /path/to/config.json:/config/config.json ghcr.io/tbxark/mcp-proxy:latest --config /config/config.json

Option B: Build from source (Go)

1. Ensure Go is installed (1.20+ recommended).
2. Clone the repository and build:

git clone https://github.com/tbxark/mcp-proxy.git
cd mcp-proxy
make build

3. Run the binary with your config:

./build/mcp-proxy --config path/to/config.json

Option C: Other deployment methods

• You can also deploy via Docker Compose or Kubernetes once you have the same configuration file prepared.
• See docs/deployment.md for additional deployment options.

Tips and notes:

• Ensure your config.json references accessible MCP backends and uses supported client types (stdio, SSE, streamable-http).
• If using Docker, map the host path to the container's /config path as shown in examples, and pass --config /config/config.json inside the container.
• The proxy exposes port 9090 by default in the examples; adjust your firewall and reverse proxy accordingly.
• Check logs if backends fail to connect or if streaming endpoints return errors; common issues include network ACLs, incorrect backend URLs, or missing authentication tokens.
• If you plan to scale, consider running multiple instances behind a load balancer with consistent config files.