stdio-http-bridge-mcp

STDIO-to-StreamableHTTP bridge for remote MCP servers. Lets local MCP clients (like Claude Desktop) connect to remote MCP servers over HTTP with OAuth/PKCE authentication.

What it does

MCP clients that only support STDIO transport (e.g. Claude Desktop) can't connect directly to remote HTTP-based MCP servers. This bridge sits in between:

Claude Desktop ←STDIO→ bridge ←HTTP→ Remote MCP Server

• Translates STDIO messages to StreamableHTTP and back
• Handles OAuth/PKCE authentication with automatic browser-based login
• Caches tokens locally with automatic expiry
• Recovers gracefully from server restarts (stale session reconnect)
• Coordinates multiple bridge processes to avoid duplicate browser popups

Usage

npx stdio-http-bridge-mcp <server-url>

Environment variables

| Variable | Required | Description | |----------|----------|-------------| | MCP_OKTA_CLIENT_ID | Yes | OAuth client ID for authentication | | MCP_BRIDGE_TOKEN_DIR | No | Override token storage directory (default: ~/.stdio-http-bridge-mcp/<hostname>) |

Claude Desktop configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "stdio-http-bridge-mcp", "https://my-mcp-server.example.com/mcp"],
      "env": {
        "MCP_OKTA_CLIENT_ID": "<your-client-id>"
      }
    }
  }
}

On first connection, the bridge opens your browser for OAuth login. Tokens are cached per server hostname at ~/.stdio-http-bridge-mcp/<hostname>/tokens.json and reused until they expire. If a refresh token is available, the bridge will attempt a silent refresh before prompting for login.

How it works

1. Claude Desktop spawns the bridge as a STDIO subprocess
2. Bridge checks for cached OAuth tokens
3. If tokens are expired and a refresh token exists, attempts a silent refresh
4. If no valid tokens, acquires a file lock and starts an OAuth/PKCE flow (opens browser)
5. After authentication, connects to the remote server via StreamableHTTP
6. Proxies MCP messages between STDIO and HTTP in both directions
7. On auth expiry or server restart, automatically re-authenticates and reconnects

Multi-process coordination

Claude Desktop sometimes spawns two bridge processes simultaneously. The bridge uses a file-based lock (~/.stdio-http-bridge-mcp/<hostname>/oauth.lock) to ensure only one process opens a browser popup. The second process waits for the first to complete authentication, then picks up the cached tokens.

Requirements

• Node.js >= 18
• The remote MCP server must support StreamableHTTP transport
• The server must expose OAuth authorization server metadata at /.well-known/oauth-authorization-server