MCP Oauth2 Proxy
ChengleiYuanLABSCO SUMMARY
A runtime you do not have, reachable over the network.
The interesting move is turning a launch command into a URL. That makes a stdio server usable from a client on a machine with no Node, no Python and no Docker, and it makes one container the single place where those runtimes are installed and updated. The other side of that: anything you proxy runs in the container with the container's filesystem and network, so what you point it at matters as much as what you install.
What it is
A streamable HTTP MCP server that proxies to stdio MCP servers. It exists for one problem the other proxies leave alone: the stdio server you want needs a command your machine does not have. xMCP runs inside a container with the common launchers preinstalled, so you address the target server by URL instead of by local command.
What you get
- A stdio MCP server addressed as a URL: the name, the command and its arguments become query parameters, for example
?name=context7&command=npx&args=-y,@upstash/context7-mcp - Launchers already present in the container so nothing has to be installed on your own machine —
npx,bunx,uvanddocker - Room to extend: add whatever else you need to the container image, and the same URL form works for it
- A local MCP Inspector alongside the server for checking what the proxied session exposes
Requirements
No account and no key. Docker: docker compose up -d, or make start. The server listens at http://localhost:3001/mcp, and the Inspector at http://localhost:6274 — the Inspector needs an auth token in the URL, which make logs prints.
Setup effort
Run a container — build the image from the repository, then point your client at it
USE CASES
01
Using an npx-only MCP server from a machine without Node
Point your client at the proxy URL with the command and arguments in the query string, and the session works as if the command were local.
02
Keeping runtimes in one place
Install the launchers once in the container instead of on every developer machine that needs to reach a stdio server.
03
Checking what a proxied server actually exposes
Open the bundled Inspector with the token from the logs and read the tool list the proxied session reports.
BEFORE YOU INSTALL
What to know first
Requires
Docker with Docker Compose
Where it runs
The documented client runs the server on your machine.
INSTALLATION
Connect your client
Server setup
TERMINAL
git clone https://github.com/kovrichard/xMCP
cd xMCP
cp .env.sample .env
docker compose up -ddocker-compose.yml reads its settings from .env, which the cp line creates from the repository's .env.sample; uncomment PORT there to serve somewhere other than 3001.
MCP Clients
Any MCP client
ANY MCP CLIENT · URL
http://localhost:3001/mcp?name=context7&command=npx&args=-y,@upstash/context7-mcpKeep http://localhost:3001/mcp as written and change the query string to the stdio server you want to reach: name is what to call it, command is its launcher (npx, bunx, uv or docker, the ones installed in the container), and args are its arguments, comma-separated. The context7 values are the project's own example.
