MCP stdio-to-HTTP Proxy

A Node.js package that provides a proxy tool to redirect MCP (Model Context Protocol) requests from stdio to HTTP servers. This tool is particularly useful when you need to connect a client that expects stdio communication (like Codex) to an MCP server that only supports HTTP.

Features

• ✅ Bidirectional proxy between stdio and HTTP
• ✅ JSON-RPC message handling
• ✅ Configurable timeouts and retry logic
• ✅ Verbose logging for debugging
• ✅ Error handling and graceful shutdown
• ✅ CLI tool with npx support

Installation

Global Installation

npm install -g mcp-stdio-http-proxy

Using with npx (Recommended)

npx mcp-stdio-http-proxy --url http://localhost:3000/mcp

Usage

Command Line Interface

mcp-stdio-http-proxy --url <http-endpoint> [options]

Options

• -u, --url <url> (required): HTTP endpoint URL for the MCP server
• -t, --timeout <ms>: Request timeout in milliseconds (default: 30000)
• -r, --retries <count>: Number of retry attempts (default: 3)
• -v, --verbose: Enable verbose logging
• -h, --help: Display help information

Examples

Basic usage:

npx mcp-stdio-http-proxy --url http://localhost:3000/mcp

With custom timeout and retries:

npx mcp-stdio-http-proxy --url http://localhost:3000/mcp --timeout 10000 --retries 5

With verbose logging:

npx mcp-stdio-http-proxy --url http://localhost:3000/mcp --verbose

Programmatic Usage

import { MCPProxy, ProxyConfig } from 'mcp-stdio-http-proxy';

const config: ProxyConfig = {
  httpEndpoint: 'http://localhost:3000/mcp',
  timeout: 30000,
  retryAttempts: 3,
  verbose: true
};

const proxy = new MCPProxy(config);
await proxy.start();

How It Works

1. Input: The proxy listens for MCP JSON-RPC messages on stdin
2. Processing: Each message is parsed and validated
3. Forwarding: Valid messages are sent to the configured HTTP endpoint
4. Response: HTTP responses are forwarded back to stdout
5. Error Handling: Errors are handled gracefully with proper JSON-RPC error responses

MCP Message Format

The proxy handles standard JSON-RPC 2.0 messages as defined by the MCP protocol:

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {}
  }
}

Integration Examples

With VS Code and Codex

1. Configure your MCP client to use this proxy as a stdio transport
2. Start the proxy pointing to your HTTP MCP server
3. The proxy will handle the protocol translation seamlessly

As a Development Tool

Use the proxy to debug MCP communication:

# Start with verbose logging
npx mcp-stdio-http-proxy --url http://localhost:3000/mcp --verbose

# Send test messages via stdin
echo '{"jsonrpc":"2.0","id":"1","method":"ping"}' | npx mcp-stdio-http-proxy --url http://localhost:3000/mcp

Error Handling

The proxy provides robust error handling:

• Parse Errors: Invalid JSON messages return proper JSON-RPC parse errors
• Network Errors: HTTP failures are retried with exponential backoff
• Timeout Errors: Configurable timeouts prevent hanging requests
• Graceful Shutdown: SIGINT/SIGTERM signals are handled properly

Development

# Clone the repository
git clone https://github.com/DragulinBogdan/mcp-stdio-http-proxy.git
cd mcp-stdio-http-proxy

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

Testing

This project includes a comprehensive test suite covering:

• Unit Tests: Core functionality of the MCPProxy class
• CLI Tests: Command-line interface validation and error handling
• Integration Tests: End-to-end message flow testing
• Edge Cases: Malformed JSON, network errors, timeouts, retry logic

Running Tests

# Run all tests
npm test

# Run tests with coverage report
npm run test:coverage

# Run tests in watch mode during development
npm run test:watch

# Run specific test files
npm test -- --testPathPattern=proxy
npm test -- --testPathPattern=cli

The test suite uses Jest and includes comprehensive mocking for HTTP requests, process I/O, and error conditions.

Contributing

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

License

MIT - see LICENSE file for details.