mcp-i-proxy

A lightweight stdio-to-HTTP proxy for MCP-I agents, enabling session persistence for Claude Desktop and other MCP clients.

Why This Exists

Claude Desktop (and some other MCP clients) re-establishes connections for every tool call, generating new session IDs each time. This breaks OAuth flows that rely on session persistence.

mcp-i-proxy solves this by:

• 🔌 Bridging stdio (Claude Desktop) to HTTP (your MCP-I server)
• 🔐 Maintaining session IDs across tool calls
• 💾 Persisting sessions across restarts
• 🌐 Auto-opening browser for OAuth consent (popup-style, like Google OAuth!)
• ⚡ Being lightweight (~30KB, zero heavy dependencies)

Installation

# No installation needed! Just use npx:
npx mcp-i-proxy https://your-agent.example.com/mcp

# Or install globally:
npm install -g mcp-i-proxy

Usage

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "my-agent": {
      "command": "npx",
      "args": ["-y", "mcp-i-proxy", "https://your-agent.example.com/mcp"]
    }
  }
}

With debug logging:

{
  "mcpServers": {
    "my-agent": {
      "command": "npx",
      "args": ["-y", "mcp-i-proxy", "--debug", "https://your-agent.example.com/mcp"]
    }
  }
}

CLI Commands

# Start proxy (main usage)
mcp-i-proxy https://your-agent.example.com/mcp

# Health check
mcp-i-proxy health https://your-agent.example.com/mcp

# Check status
mcp-i-proxy status https://your-agent.example.com/mcp

# With options
mcp-i-proxy --debug --timeout 60000 https://your-agent.example.com/mcp

Options

| Option | Description | Default | |--------|-------------|---------| | --debug | Enable debug logging | false | | --no-auto-auth | Don't auto-open browser for OAuth | false | | --no-session | Disable session persistence | false | | --transport <type> | Transport type: streamablehttp or sse | streamablehttp | | --timeout <ms> | Request timeout in milliseconds | 30000 | | --header <key:value> | Add custom header (repeatable) | - |

Features

🔐 Session Persistence

Sessions are automatically persisted to ~/.mcp-i-proxy/sessions.json. When Claude Desktop restarts, the proxy restores the session, avoiding re-authentication.

🌐 Auto-Open Browser for OAuth

When a tool requires authorization, the proxy automatically opens your browser to the consent URL:

🔐 Authorization Required

Tool "greet" requires your permission.
Scopes: greet:execute

→ Please visit this URL to authorize:
  https://your-agent.example.com/consent?session=abc123

🌐 Browser opened for authorization

📊 Health Check

Quickly verify your MCP server is reachable:

$ mcp-i-proxy health https://your-agent.example.com/mcp

┌─────────────────────────────────────────────┐
│  🏥 MCP-I Server Health Check               │
├─────────────────────────────────────────────┤
│  Server:  https://your-agent.example.com    │
│  Status:  ✓ Healthy                         │
│  Latency: 42   ms                           │
└─────────────────────────────────────────────┘

🐛 Debug Mode

Enable detailed logging to troubleshoot issues:

mcp-i-proxy --debug https://your-agent.example.com/mcp

Architecture

┌─────────────────┐     stdio      ┌─────────────────┐     HTTP     ┌─────────────────┐
│  Claude Desktop │ ────────────▶ │   mcp-i-proxy   │ ──────────▶ │   MCP-I Server  │
│  (MCP Client)   │ ◀──────────── │   (this pkg)    │ ◀────────── │   (your agent)  │
└─────────────────┘               └─────────────────┘             └─────────────────┘
                                         │
                                         ▼
                                  ~/.mcp-i-proxy/
                                   sessions.json

The proxy:

1. Reads JSON-RPC messages from stdin (Claude Desktop)
2. Forwards them to your MCP-I server via HTTP
3. Manages the Mcp-Session-Id header
4. Persists sessions to disk
5. Writes responses to stdout (back to Claude Desktop)

Programmatic Usage

import { MCPIProxy, createLogger } from 'mcp-i-proxy';

const proxy = new MCPIProxy({
  serverUrl: 'https://your-agent.example.com/mcp',
  debug: true,
  autoAuth: true,
});

await proxy.start();

Comparison with Other Solutions

| Feature | mcp-i-proxy | Python mcp-proxy | |---------|-------------|------------------| | Runtime | Node.js | Python | | Install | npx (auto) | pip install | | Size | ~30KB | ~50KB | | MCP-I Features | ✅ Built-in | ❌ Generic | | Auto-Open Browser | ✅ | ❌ | | Session Persistence | ✅ File-based | ❌ Memory only |

Requirements

• Node.js 18 or later
• Internet connection to MCP-I server

Troubleshooting

"Session expired" errors

Try clearing the session cache:

rm ~/.mcp-i-proxy/sessions.json

Browser doesn't open for OAuth

Check that you have a default browser set. You can also manually copy the consent URL from the logs.

Connection timeout

Increase the timeout:

mcp-i-proxy --timeout 60000 https://your-agent.example.com/mcp

License

MIT © Kya OS

Related

• @kya-os/mcp-i - MCP-I framework
• @kya-os/mcp-i-cloudflare - Cloudflare Workers adapter
• MCP Specification - Model Context Protocol