mcpx

MCP stdio-to-HTTP bridge for connecting Claude Desktop, Cursor, and other MCP clients to HTTP-based MCP servers.

Why?

MCP clients like Claude Desktop communicate via stdio (standard input/output), but many MCP servers expose an HTTP endpoint. This bridge translates between the two, enabling seamless connectivity.

┌─────────────────┐       stdio        ┌─────────┐       HTTP        ┌─────────────┐
│  Claude Desktop │  ←──────────────→  │  mcpx   │  ←─────────────→  │  MCP Server │
│  Cursor         │                    │         │                    │  (Gateway)  │
│  Windsurf       │                    └─────────┘                    └─────────────┘
└─────────────────┘

Installation

No installation required! Use directly with npx:

npx @zoeylabs/mcpx

Or install globally:

npm install -g @zoeylabs/mcpx

Usage

Claude Desktop

Add to your claude_desktop_config.json:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@zoeylabs/mcpx"],
      "env": {
        "MCP_URL": "https://mcp-server.example.com/mcp",
        "MCP_API_KEY": "your-api-key"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project or configure via Settings → MCP Servers:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@zoeylabs/mcpx"],
      "env": {
        "MCP_URL": "https://mcp-server.example.com/mcp",
        "MCP_API_KEY": "your-api-key"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@zoeylabs/mcpx"],
      "env": {
        "MCP_URL": "https://mcp-server.example.com/mcp",
        "MCP_API_KEY": "your-api-key"
      }
    }
  }
}

Continue (VS Code)

Add to ~/.continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@zoeylabs/mcpx"],
          "env": {
            "MCP_URL": "https://mcp-server.example.com/mcp",
            "MCP_API_KEY": "your-api-key"
          }
        }
      }
    ]
  }
}

Cline (VS Code)

Open VS Code Command Palette → "Cline: Open MCP Settings" and add:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@zoeylabs/mcpx"],
      "env": {
        "MCP_URL": "https://mcp-server.example.com/mcp",
        "MCP_API_KEY": "your-api-key"
      }
    }
  }
}

Configuration

All configuration is via environment variables:

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | MCP_URL | Yes | - | MCP server URL (HTTP or HTTPS) | | MCP_API_KEY | No | - | API key for authentication | | MCP_USE_BEARER | No | false | Use Authorization: Bearer instead of X-API-Key header | | MCP_TIMEOUT | No | 30000 | Request timeout in milliseconds | | MCP_INSECURE | No | false | Skip SSL certificate validation (for self-signed certs) | | MCP_DEBUG | No | false | Enable debug logging to stderr |

Legacy Environment Variables

For backward compatibility, these are also supported:

| Variable | Maps To | |----------|---------| | GATEWAY_URL | MCP_URL | | GATEWAY_API_KEY | MCP_API_KEY | | DEBUG | MCP_DEBUG |

Features

• Zero dependencies - Pure Node.js, no external packages
• Streamable HTTP transport - Implements MCP 2025-03-26 specification
• Session management - Automatic session ID handling
• SSE support - Handles Server-Sent Events responses
• Configurable auth - Supports X-API-Key and Bearer token authentication
• Timeout handling - Configurable request timeouts
• Debug mode - Detailed logging for troubleshooting

Troubleshooting

Enable debug logging

Set MCP_DEBUG=true to see detailed logs:

{
  "env": {
    "MCP_URL": "https://server.example.com/mcp",
    "MCP_DEBUG": "true"
  }
}

Debug output goes to stderr so it won't interfere with the stdio protocol.

Self-signed certificates

For development with self-signed SSL certificates:

{
  "env": {
    "MCP_URL": "https://localhost:8100/mcp",
    "MCP_INSECURE": "true"
  }
}

Connection refused

1. Verify the MCP server is running
2. Check the URL is correct (including /mcp path)
3. Ensure firewall allows the connection
4. Try with MCP_DEBUG=true for more details

Protocol Support

mcpx implements the Streamable HTTP transport from the MCP specification:

• Individual POST requests for each JSON-RPC message
• Session ID tracking via Mcp-Session-Id header
• SSE responses for streaming results
• Proper handling of 202 Accepted for notifications

License

MIT