MCP Proxy Server by adamwattis
adamwattisLABSCO SUMMARY
Aggregation plus an editing layer over other people's tools.
Most proxies stop at merging tool lists. This one lets you disable the tools you never want the model to see and rewrite names and descriptions that read badly, which is the practical fix when a backend ships a dozen tools and you want three. The retry layer is the other quiet win: an SSE backend that drops mid-call gets reconnected and the call replayed rather than surfacing as a failure.
What it is
An aggregating proxy: it connects to a list of backend MCP servers — stdio, SSE or Streamable HTTP — and re-exposes their combined tools and resources as a single server, itself reachable over stdio, SSE (/sse) or Streamable HTTP (/mcp). An optional browser admin UI manages the server list and the per-tool overrides.
What you get
- One connection in your client that fans out to every backend, with requests routed to the right one and each backend's key joined to the original tool name by a separator that defaults to
__ - Per-tool control: hide a tool from clients entirely, or override its display name and description, written to
config/tool_config.jsonand applied without restarting - Backend definitions that accept a command and args for stdio, or a URL plus
apiKey/bearerTokenfor SSE and HTTP, withactiveset tofalseto park one without deleting it - A live config reload that picks up server and tool changes in place
- Retries with exponential backoff and jitter on every transport — a dropped SSE connection is re-established before the call is retried, and a crashed stdio backend is restarted; each is tunable through
RETRY_SSE_TOOL_CALL,SSE_TOOL_CALL_MAX_RETRIESand their HTTP and stdio counterparts - Backend errors returned to the client as standard JSON-RPC error responses rather than swallowed
- Install commands you can define per stdio backend and trigger from the admin UI, with stdout and stderr streamed live into the browser
Requirements
Node, or the published container image ghcr.io/ptbsare/mcp-proxy-server/mcp-proxy-server. The package.json is marked private (version 0.4.1), so this is a clone-and-build or Docker install rather than an npm one. HTTP mode listens on PORT, default 3663. Authentication on /sse and /mcp is off unless you set ALLOWED_KEYS or ALLOWED_TOKENS. The admin UI is off unless ENABLE_ADMIN_UI=true, and it ships with ADMIN_USERNAME defaulting to admin and ADMIN_PASSWORD to password — the README says change it. Two features carry the project's own warnings: the built-in web terminal gives shell access to the host the proxy runs on, and installCommands execute arbitrary shell.
Setup effort
Build from source — clone the repository and build it, then follow the steps on this page and add the configuration for your client
USE CASES
01
Collapsing a dozen MCP entries in your client into one
List every backend in config/mcp_server.json and point the client at the proxy's stdio command or its /mcp endpoint instead.
02
Cutting a noisy backend down to the tools you actually use
Open the admin UI, disable the rest, and give the survivors names and descriptions that read clearly to the model.
03
Sharing one set of backends across a team
Run the container, set ALLOWED_TOKENS, and hand each client a bearer token for the /mcp endpoint.
04
Surviving flaky backends
Leave the retry defaults on so a dropped SSE session or a crashed stdio process is re-established and the tool call replayed instead of failing outright.
BEFORE YOU INSTALL
What to know first
Tools you get
0 tools when we connected.
Requires
Node.js with npm to build from source, or Docker for the published image ghcr.io/ptbsare/mcp-proxy-server/mcp-proxy-server
INSTALLATION
Connect your client
Server setup
TERMINAL
git clone https://github.com/ptbsare/mcp-proxy-server
cd mcp-proxy-server
npm install
npm run buildList your backend servers in config/mcp_server.json — the repository ships config/mcp_server.json.example as a starting point.
MCP Clients
Claude Desktop — stdio
CLAUDE DESKTOP — STDIO · JSON
{
"mcpServers": {
"mcp-proxy": {
"name": "MCP Proxy (Aggregator)",
"command": "<YOUR_PATH_TO_MCP_PROXY_SERVER>/build/index.js",
"env": {
"NODE_ENV": "production",
"TOOLS_FOLDER": "/custom/path/for/proxy/tools"
}
}
}
}<YOUR_PATH_TO_MCP_PROXY_SERVER>/build/index.js is the full path to build/index.js in the folder you cloned and built. The proxy reads config/mcp_server.json relative to where it is started, so keep that config folder in the clone. TOOLS_FOLDER is optional: it is only where the admin UI installs stdio backends (default: a tools folder in the proxy's working directory) — point it at a folder you can write to, or delete the line.
Any MCP client — HTTP
ANY MCP CLIENT — HTTP · TERMINAL
docker pull ghcr.io/ptbsare/mcp-proxy-server/mcp-proxy-server:latest
docker run -d -p 3663:3663 -e PORT=3663 -v ./my_config:/mcp-proxy-server/config --name mcp-proxy-server ghcr.io/ptbsare/mcp-proxy-server/mcp-proxy-server:latestmy_config is a folder on your machine holding mcp_server.json, the list of backend servers the proxy connects to.
ANY MCP CLIENT — HTTP · JSON
{
"mcpServers": {
"my-proxy-http": {
"type": "http",
"name": "MCP Proxy (Streamable HTTP)",
"url": "http://localhost:3663/mcp"
}
}
}
