How do I use MCP HTTP-stdio Proxy?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP HTTP-stdio Proxy run the update tool to refresh the remote server connection and tools" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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-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

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.