Mcp Proxy

What is Mcp Proxy about?

Mcp Proxy aggregates the tools and capabilities of several MCP resource servers and exposes them through one HTTP server. It can relay requests to the underlying MCP clients using Server‑Sent Events (SSE) or streamable‑HTTP, providing a unified entry point for downstream applications.

How to use Mcp Proxy?

1. Install – either build from source, install with go install, or run the official Docker image.
2. Create a configuration file (JSON) that defines the proxy itself (mcpProxy) and the list of MCP servers (mcpServers).
3. Start the proxy:

   ./build/mcp-proxy --config path/to/config.json
   # or, when using Docker
   docker run -d -p 9090:9090 -v /path/to/config.json:/config/config.json ghcr.io/tbxark/mcp-proxy:latest
   

4. Access each aggregated client via URLs of the form:
   • SSE: http(s)://{baseURL}/{clientName}/sse
   • HTTP streaming: http(s)://{baseURL}/{clientName}/mcp

Key features of Mcp Proxy

• Multi‑client aggregation – combine any number of MCP servers (stdio, SSE, or HTTP‑streaming) into one service.
• Dual transport support – choose between SSE and streamable‑HTTP for downstream consumption.
• Flexible configuration – JSON‑based config with default options, per‑client overrides, and tool filtering.
• Authentication – optional token‑based auth checked against the Authorization header.
• Logging & panic control – enable request logging and decide whether invalid clients should cause a panic.
• Docker ready – official image with built‑in support for common client launch methods (npx, uvx).

Use cases of Mcp Proxy

• Centralized AI tool gateway – expose a suite of model‑driven capabilities (e.g., GitHub operations, web fetch, map services) behind a single endpoint for internal tools or third‑party integrations.
• Environment isolation – run each MCP server in its own subprocess or container while presenting a unified API to consumers.
• Dynamic tool filtering – enable or block specific tools per client without modifying the underlying MCP server code.
• Rapid prototyping – spin up a proxy locally with a minimal config to test multiple MCP services together.

FAQ from the Mcp Proxy

• Q: Do I need to configure auth tokens for every client? A: No. authTokens defined under mcpProxy act as defaults. Individual clients can override them; if omitted, the proxy defaults are used.
• Q: What transport should I pick? A: Use sse for simple event‑driven consumption, or streamable-http when you need raw HTTP streaming (e.g., for large payloads).
• Q: How can I filter tools? A: Add a toolFilter under a client’s options with mode set to allow or block and list the tool names.
• Q: Can I run the proxy in production? A: Yes. The Docker image is production‑ready; configure proper TLS termination at your ingress layer and set appropriate auth tokens.
• Q: Where do I find the list of available tools for a client? A: Start the proxy without a toolFilter. The console will log messages like <server_name> Adding tool <tool_name> for each registered tool.

MCP Proxy Server

An MCP proxy that aggregates multiple MCP servers behind a single HTTP entrypoint.

Features

• Proxy multiple MCP clients: aggregate tools, prompts, and resources from many servers.
• SSE and streamable HTTP: serve via Server‑Sent Events or streamable HTTP.
• Flexible config: supports stdio, sse, and streamable-http client types.

Documentation

• Configuration: docs/configuration.md
• Usage: docs/usage.md
• Deployment: docs/deployment.md
• Claude config converter: https://tbxark.github.io/mcp-proxy

Quick Start

Build from source

git clone https://github.com/TBXark/mcp-proxy.git
cd mcp-proxy
make build
./build/mcp-proxy --config path/to/config.json

Install via Go

go install github.com/TBXark/mcp-proxy@latest

Docker

The image includes support for launching MCP servers via npx and uvx.

docker run -d -p 9090:9090 -v /path/to/config.json:/config/config.json ghcr.io/tbxark/mcp-proxy:latest
# or provide a remote config
docker run -d -p 9090:9090 ghcr.io/tbxark/mcp-proxy:latest --config https://example.com/config.json

More deployment options (including docker‑compose) are in docs/deployment.md.

Configuration

See full configuration reference and examples in docs/configuration.md. An online Claude config converter is available at: https://tbxark.github.io/mcp-proxy

Usage

Command‑line flags, endpoints, and auth examples are documented in docs/usage.md.

Thanks

• This project was inspired by the adamwattis/mcp-proxy-server project
• If you have any questions about deployment, you can refer to 《在 Docker 沙箱中运行 MCP Server》(@ccbikai)

License

This project is licensed under the MIT License. See the LICENSE file for details.