Bridge stdio-based clients to HTTP-based MCP servers
MCP HTTP-stdio Proxy
A Node.js implementation of a Model Context Protocol (MCP) proxy that enables communication between stdio-based clients (like Antigravity) and HTTP-based MCP servers (running with streamableHttp).
Overview
This proxy allows you to use remote or HTTP-hosted MCP servers as if they were local stdio servers. It handles the JSON-RPC communication, session management, and optional authentication seamlessly.
graph LR
Client[Antigravity / Stdio Client] -->|stdio| Proxy[MCP Proxy]
Proxy -->|HTTP JSON-RPC| Upstream[Upstream MCP Server]
Features
- Protocol Translation: Bridges MCP over stdio to MCP over HTTP.
- Session Management:
- Automatically handles upstream initialization.
- Persists session IDs in
~/.mcp-session-cachefor continuity. - Automatic retries on session expiration or "Not Initialized" errors.
- Dynamic Tool List: Automatically injects an
updatetool to manually refresh the upstream connection and clear the session cache. - Broad Support: Proxies tools, resources, prompts, completions, and logging levels.
- Authentication: Supports optional authorization headers for secure upstream servers.
- Timeout Support: Configurable request timeouts.
Installation
- Clone or copy the project files.
- Install dependencies:
npm install
Configuration
The proxy can be configured using environment variables or a .env file:
| Variable | Description | Default |
|---|---|---|
UPSTREAM_MCP_URL |
The URL of the target HTTP MCP server. | http://localhost:8080/mcp |
UPSTREAM_AUTH |
Optional authentication header value (e.g., Bearer ...). |
(none) |
MCP_TIMEOUT_MS |
Timeout for upstream requests in milliseconds. | 15000 |
MCP_SESSION_ID |
Manually specify an initial session ID. | (none) |
Usage
Direct Execution
You can run the proxy directly and optionally pass the upstream URL as the first argument:
node mcp-proxy.js https://your-remote-mcp-server.com/mcp
Run using npx (from GitHub)
You can run the proxy directly without cloning using npx:
npx -y kiennh/mcp-http-stdio https://your-remote-mcp-server.com/mcp
Run using Docker
The proxy is available as a Docker image:
docker run -i --rm \
-e UPSTREAM_MCP_URL="https://your-remote-mcp-server.com/mcp" \
-e UPSTREAM_AUTH="Bearer YOUR_TOKEN" \
ghcr.io/kiennh/mcp-http-stdio:latest
Integration with Antigravity
To use this proxy with Antigravity, add it to your mcp_config.json:
{
"mcpServers": {
"my-remote-server": {
"command": "npx",
"args": ["-y", "kiennh/mcp-http-stdio", "https://api.example.com/mcp"],
"env": {
"UPSTREAM_AUTH": "Bearer YOUR_TOKEN"
}
}
}
}
Custom 'update' Tool
The proxy automatically adds a tool named update to the list of available tools. Calling update will:
- Clear the local session cache (
~/.mcp-session-cache). - Force a re-initialization of the upstream server on the next request.
- This is useful if the upstream server's tools have changed or the session has become desynchronized.
License
ISC
Tools (1)
updateClears the local session cache and forces a re-initialization of the upstream server on the next request.Environment Variables
UPSTREAM_MCP_URLThe URL of the target HTTP MCP server.UPSTREAM_AUTHOptional authentication header value (e.g., Bearer ...).MCP_TIMEOUT_MSTimeout for upstream requests in milliseconds.MCP_SESSION_IDManually specify an initial session ID.Configuration
{"mcpServers": {"my-remote-server": {"command": "npx", "args": ["-y", "kiennh/mcp-http-stdio", "https://api.example.com/mcp"], "env": {"UPSTREAM_AUTH": "Bearer YOUR_TOKEN"}}}}