mcp-proxy: A Go Server That Aggregates Multiple MCP Backends Behind One HTTP Endpoint

What mcp-proxy does and the problem it addresses

The Model Context Protocol (MCP) allows AI clients to connect to servers that expose tools, prompts, and resources. An AI client configured to use several MCP servers typically maintains a direct connection to each one. As the number of servers grows, the client configuration grows with it, and every deployment that wants to use those servers must be configured separately.

mcp-proxy introduces a single aggregation layer. You point the proxy at multiple MCP servers through a config.json file, and the proxy merges their tools, prompts, and resources into one combined catalogue. An AI client connects to the proxy instead of to each individual server. Adding or removing a server means updating the proxy's config.json, not reconfiguring every client.

The repository is inspired by adamwattis/mcp-proxy-server, which the README credits directly. The tbxark version is written in Go, ships as a single binary, and adds OAuth support and a Docker image that bundles Node.js and Python runtimes for running JavaScript and Python MCP servers without separate installations.

Client types and transport protocols

mcp-proxy supports three types of upstream MCP client connections as described in the README:

- stdio: connects to a server through standard input and output. This is the most common type for locally running MCP servers. - sse: connects to a server using Server-Sent Events. - streamable-http: connects using the newer streamable HTTP transport.

On the outgoing side (toward AI clients), the proxy serves via SSE or streamable HTTP. This means an AI client that only speaks one transport can connect to the proxy even if some upstream servers use a different protocol.

The documentation is split across three files in the docs/ directory: docs/configuration.md for the full config.json reference, docs/usage.md for command-line flags and endpoint details, and docs/deployment.md for deployment patterns including Docker Compose. An online Claude config converter is available at https://tbxark.github.io/mcp-proxy to help convert Claude's native MCP config format into mcp-proxy's config.json.

Installing and running mcp-proxy

Three installation paths are available. The fastest single-command path for Go users is:

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

This installs the mcp-proxy binary into the Go bin directory. Run it with:

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

To build from source:

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

The Docker path is suitable for environments where running npx or uvx servers is required, since the official image bundles Node.js and Python:

docker run -d -p 9090:9090 -v /path/to/config.json:/config/config.json ghcr.io/tbxark/mcp-proxy:latest

The docker-compose.yml in the repository provides a ready-made service definition that mounts config.json and exposes port 9090. The README also shows that a remote config URL is accepted: you can pass --config https://example.com/config.json and the proxy will fetch its configuration over HTTP at startup.

OAuth support for downstream servers

Some MCP servers require interactive OAuth authentication, where a browser-based authorization flow must complete before the server accepts tool calls. Without a proxy, every AI client that uses such a server would need to perform this flow separately. mcp-proxy handles OAuth once against the downstream server and then holds the token for all callers.

The README describes this as: authorize once against downstream servers that require interactive OAuth, then let the proxy hold and refresh the token for every caller. The OAuth support is documented in the CONFIGURATION.md and tested in the repository's oauth_test.go and oauth_store_test.go files at the root level.

The repository also includes a security_fixes_test.go file, which indicates that security-related changes have been tested. The go.mod file shows the project uses Go 1.25.5 and depends on mark3labs/mcp-go v1.1.0 as the core MCP library, plus golang.org/x/sync for concurrent operations.

Configuration and the config.json structure

The proxy's configuration lives in a single JSON file. The full reference is in docs/configuration.md. The repository root contains a sample config.json that can be used as a starting point.

The repository also provides an online Claude config converter at https://tbxark.github.io/mcp-proxy. This tool is specifically for users who have an existing Claude MCP configuration file and want to import it into mcp-proxy's format without rewriting it manually. The converter is a static web tool hosted on GitHub Pages.

The docker-compose.yaml in the repository shows the basic structure: mount config.json to /config/config.json inside the container, expose port 9090, and set restart: always for production use. An alternative pattern shown in the commented portion of the same file uses a Caddy sidecar to serve the config.json file over HTTP, so the proxy container can fetch its config from a URL instead of needing a volume mount.

Release history and when to consider alternatives

The repository has three recent releases: v1.1.0 on 2026-09-15, v0.58.0 on 2026-08-16, and v0.43.2 on 2026-01-04. The jump from v0.58.0 to v1.1.0 in a single month suggests a significant version that introduced breaking or stabilising changes. The CHANGELOG.md file in the repository would provide the specifics, but it is not reproduced in the README.

mcp-proxy is a self-hosted component. You run it, you manage it, and its availability is your responsibility. For teams who want a managed alternative, the related searches for this project include "mcp proxy vs mcp gateway". An MCP gateway service would add features like authentication between clients and the proxy, rate limiting, and hosted management. mcp-proxy does not include those features: it is a proxy layer, not a full API gateway. Teams with strict access control requirements between AI clients and the proxy will need to add that layer themselves, such as with a reverse proxy like Caddy or nginx in front of mcp-proxy.

The project is written in Go and compiles to a single static binary (CGO_ENABLED=0 in the Makefile), which simplifies deployment significantly compared to Python or Node.js alternatives that require runtime management. The MIT licence permits commercial use.

Editorial conclusion

mcp-proxy suits teams and individuals who run several MCP servers and want a single entry point rather than configuring each AI client to speak to every server individually. It also solves the OAuth problem for downstream servers like Notion, where interactive authentication is needed once and then the proxy holds the token on behalf of all callers. It is not a hosted service: you run it yourself, manage the config.json, and expose port 9090 (or another port) yourself. The Docker image is the fastest path to production because it bundles Node.js and Python so that servers launched via npx and uvx do not require a separate runtime install. The last push was on 2026-09-15, and releases are versioned. The MIT licence places no restrictions on commercial use.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. tbxark/mcp-proxy on GitHub