# 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.
```mermaid
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-cache` for continuity.
- Automatic retries on session expiration or "Not Initialized" errors.
- **Dynamic Tool List:** Automatically injects an `update` tool 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
1. Clone or copy the project files.
2. Install dependencies:
```bash
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:
```bash
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`:
```bash
npx -y kiennh/mcp-http-stdio https://your-remote-mcp-server.com/mcp
```
### Run using Docker
The proxy is available as a Docker image:
```bash
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`:
```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:
1. Clear the local session cache (`~/.mcp-session-cache`).
2. Force a re-initialization of the upstream server on the next request.
3. This is useful if the upstream server's tools have changed or the session has become desynchronized.
## License
ISC
