Content
# mcp-stdio-proxy
A small, dependency-light proxy that lets any **local STDIO** [Model Context Protocol](https://modelcontextprotocol.io) client talk to a **remote MCP server** over HTTP — including servers that require **OAuth 2.1** authentication.
It is the missing glue for clients (Cursor, Claude Desktop, Windsurf, VS Code, Cline, Continue, Highlight, Augment, …) that still only support stdio when you want to point them at an HTTP-based MCP server.
```
┌──────────────┐ stdio ┌────────────────────┐ HTTP / SSE ┌──────────────────┐
│ MCP client │ ─────────────▶ │ mcp-stdio-proxy │ ─────────────────▶ │ Remote MCP │
│ (IDE/agent) │ ◀───────────── │ (this package) │ ◀───────────────── │ server │
└──────────────┘ └────────────────────┘ └──────────────────┘
```
---
## ✨ Features
- **STDIO ↔ HTTP/SSE bridge** — pipes JSON-RPC messages between a stdio transport and a remote MCP endpoint.
- **Streamable HTTP and SSE** — supports both modern Streamable HTTP and legacy SSE transports of the MCP spec.
- **OAuth 2.1 with PKCE** — opens a browser, runs a local callback server, persists tokens, refreshes automatically.
- **Static API key** — pass an `API_KEY` env var to use bearer auth instead of OAuth.
- **Auto-reconnect** — transparently reconnects to the remote and replays the `initialize` request if the connection drops.
- **Single binary via `npx`** — no install required.
---
## 🚀 Quick start
```bash
npx -y mcp-stdio-proxy <https://your-mcp-server-url>
```
The proxy reads JSON-RPC from stdin, forwards it to the remote server, and writes responses back to stdout. That is exactly what every MCP client expects from a stdio server, so you can drop it into any client config that supports `command` + `args`.
If the remote server requires OAuth, your default browser will open the first time you run the proxy. Tokens are cached on disk (under your OS user-config directory) so subsequent runs are silent.
### Environment variables
| Variable | Purpose |
|-------------------|-------------------------------------------------------------------------|
| `MCP_SERVER_URL` | Remote URL (used if no positional argument is given). |
| `API_KEY` | If set, sent as `Authorization: Bearer <API_KEY>` instead of OAuth. |
| `DEBUG` | Set to `true` to print verbose JSON-RPC traffic to stderr. |
---
## 🔌 Client configuration
Drop one of these snippets into your client's MCP config. Replace the URL with your own remote MCP server.
### Cursor (`~/.cursor/mcp.json`)
```json
{
"mcpServers": {
"my-remote-server": {
"command": "npx",
"args": ["-y", "mcp-stdio-proxy", "https://your-mcp-server-url"]
}
}
}
```
### Claude Desktop (Settings → Developer → *Edit Config*)
```json
{
"mcpServers": {
"my-remote-server": {
"command": "npx",
"args": ["-y", "mcp-stdio-proxy", "https://your-mcp-server-url"]
}
}
}
```
### Windsurf (`~/.codeium/windsurf/mcp_config.json`)
```json
{
"mcpServers": {
"my-remote-server": {
"command": "npx",
"args": ["-y", "mcp-stdio-proxy", "https://your-mcp-server-url"]
}
}
}
```
### VS Code (`.vscode/mcp.json`)
```json
{
"servers": {
"my-remote-server": {
"command": "npx",
"args": ["-y", "mcp-stdio-proxy", "https://your-mcp-server-url"]
}
}
}
```
### Cline / Continue / other clients (`cline_mcp_settings.json` and similar)
```json
{
"mcpServers": {
"my-remote-server": {
"command": "npx",
"args": ["-y", "mcp-stdio-proxy", "https://your-mcp-server-url"],
"disabled": false,
"autoApprove": []
}
}
}
```
### Static API key
```json
{
"mcpServers": {
"my-remote-server": {
"command": "npx",
"args": ["-y", "mcp-stdio-proxy", "https://your-mcp-server-url"],
"env": { "API_KEY": "sk-..." }
}
}
}
```
---
## 🐳 Docker
```bash
docker build -t mcp-stdio-proxy .
docker run --rm -i mcp-stdio-proxy https://your-mcp-server-url
```
For OAuth flows you'll want `--network=host` (Linux) or to expose the callback port so the browser can reach it. For most users, running via `npx` on the host is simpler.
---
## 🛠️ Development
```bash
npm install
npm run build
node dist/index.js https://your-mcp-server-url
```
Run with `DEBUG=true` to see every JSON-RPC frame on stderr.
---
## 📄 License
MIT — see [LICENSE](./LICENSE).
