mcp-stdio-http-bridge

Universal bridge between stdio-based MCP clients (like Claude Code) and HTTP-based MCP servers.

Why This Package?

Many MCP (Model Context Protocol) clients, including Claude Code CLI, only support stdio transport. However, deploying MCP servers as HTTP services offers better scalability, monitoring, and deployment options. This bridge enables stdio-only clients to connect to HTTP-based MCP servers seamlessly.

Key Benefits

• 🔌 Universal Compatibility - Connect any stdio MCP client to any HTTP MCP server
• 🐳 Docker Ready - Perfect for containerized MCP server deployments
• 🔄 Session Management - Automatic session ID handling
• 📡 Streaming Support - Handles both JSON and SSE responses
• 🛡️ Production Ready - Comprehensive error handling and health checks
• 📦 Zero Dependencies - Only uses commander for CLI parsing

Installation

Global Installation

npm install -g @thefoot/mcp-stdio-http-bridge

Local Installation

npm install @thefoot/mcp-stdio-http-bridge

Using npx (no installation)

npx @thefoot/mcp-stdio-http-bridge --url http://localhost:3200/mcp

Usage

Command Line

# Basic usage
mcp-bridge --url http://localhost:3200/mcp

# With options
mcp-bridge \
  --url http://localhost:3200/mcp \
  --timeout 60000 \
  --debug

# Using environment variable
MCP_HTTP_URL=http://localhost:3200/mcp mcp-bridge

# Skip health check (useful for custom endpoints)
mcp-bridge --url http://localhost:3200/mcp --no-health-check

CLI Options

Option	Description	Default	Environment Variable
-u, --url <url>	MCP server URL	http://localhost:3200/mcp	MCP_HTTP_URL
-t, --timeout <ms>	Request timeout in milliseconds	30000
-l, --log-level <level>	Log level (trace/debug/info/warn/error/fatal)	info	LOG_LEVEL
--no-health-check	Skip health check on startup	false
-V, --version	Display version number
-h, --help	Display help

With Claude Code

Configure in your project's .mcp.json:

{
  "mcpServers": {
    "my-server": {
        "command": "sh",
        "args": [
            "-c",
            "node $(npm root)/@thefoot/mcp-stdio-http-bridge/src/cli.js"
        ],
        "env": {
            "MCP_HTTP_URL": "http://localhost:3200/mcp"
        }
    }
  }
}

Or install globally and use directly:

{
  "mcpServers": {
    "my-server": {
      "command": "mcp-bridge",
      "args": ["--url", "http://localhost:3200/mcp"]
    }
  }
}

Programmatic Usage

import { MCPBridge } from '@thefoot/mcp-stdio-http-bridge';

const bridge = new MCPBridge({
  url: 'http://localhost:3200/mcp',
  timeout: 30000,
  logLevel: 'debug', // Set log level programmatically
});

// Listen to events
bridge.on('start', () => console.log('Bridge started'));
bridge.on('error', (error) => console.error('Error:', error));
bridge.on('session', (sessionId) => console.log('Session:', sessionId));

// Start the bridge
await bridge.start();

// Stop when done
bridge.stop();

API

Class: MCPBridge

Constructor Options

{
  url?: string,      // MCP server URL (default: 'http://localhost:3200/mcp')
  timeout?: number,  // Request timeout in ms (default: 30000)
  logLevel?: string, // Log level: trace/debug/info/warn/error/fatal (default: 'info')
  logger?: Object    // Custom Pino logger instance
}

Methods

• start(options?) - Start the bridge
• stop() - Stop the bridge
• checkHealth() - Check if HTTP server is reachable

Events

• start - Emitted when bridge starts successfully
• stop - Emitted when bridge stops
• error - Emitted on errors
• session - Emitted when session ID is established

Health Checks

The bridge automatically checks the /health endpoint before starting. Your MCP server should implement this endpoint:

app.get('/health', (req, res) => {
  res.json({ status: 'healthy' });
});

To skip health checks:

mcp-bridge --url http://localhost:3200/mcp --no-health-check

Requirements

• Node.js >= 18.0.0
• MCP server with HTTP/Streamable HTTP transport
• MCP server should implement /health endpoint (optional)

Troubleshooting

Debug Mode and Logging

Enable detailed logging to see what's happening:

# Set log level via environment variable
LOG_LEVEL=debug mcp-bridge --url http://localhost:3200/mcp

# Or via CLI option
mcp-bridge --url http://localhost:3200/mcp --log-level debug

# Available log levels: trace, debug, info, warn, error, fatal
mcp-bridge --log-level trace  # Most verbose

The bridge uses Pino for structured logging with pretty formatting in development and JSON in production.

Common Issues

1. "MCP server not reachable"

   • Ensure your HTTP MCP server is running
   • Check the URL is correct
   • Verify network connectivity

2. "Parse error"

   • Verify your MCP server returns valid JSON-RPC responses
   • Check Content-Type headers

3. Session issues

   • Ensure your server properly handles Mcp-Session-Id headers
   • Check session timeout settings

Development

# Clone repository
git clone https://github.com/wsd-team-dev/mcp-stdio-http-bridge.git
cd mcp-stdio-http-bridge

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run linting
npm run lint

# Format code
npm run format

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT © WSD Team

Related

• Model Context Protocol
• MCP Specification
• Claude Code

Support

For issues and questions, please use the GitHub issue tracker.