mcp-http-to-stdio

MCP HTTP-to-STDIO Bridge

A Python bridge utility that enables Claude Desktop to connect to HTTP-based MCP (Model Context Protocol) servers via stdio transport.

Overview

Claude Desktop uses stdio (stdin/stdout) to communicate with MCP servers, but many MCP servers expose HTTP endpoints. This bridge translates between the two protocols, allowing Claude Desktop to use HTTP-based MCP servers.

Architecture:

Claude Desktop (stdio/JSON-RPC) ←→ mcp-http-to-stdio (bridge) ←→ HTTP MCP Server

Features

• ✅ Protocol Translation: Converts stdio JSON-RPC to HTTP POST requests
• ✅ Authentication: Supports custom header-based authentication
• ✅ Connection Pooling: Optimized HTTP connections with keep-alive and retry logic
• ✅ Error Handling: Comprehensive error responses for network, auth, and server errors
• ✅ Logging: File and stderr logging for debugging
• ✅ Performance: Tracks request timing and logs slow requests

Prerequisites

• Python 3.8+
• An HTTP-based MCP server to connect to
• Claude Desktop

Installation

From PyPI (Recommended)

pip install mcp-http-to-stdio

This installs the package globally and makes the mcp-http-to-stdio command available system-wide.

From Source

git clone https://github.com/your-org/agentic-enterprise.git
cd agentic-enterprise/packages/mcp-http-to-stdio
pip install -e .

Configuration

Claude Desktop Config File Location

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

Basic Configuration

{
  "mcpServers": {
    "my-http-mcp-server": {
      "command": "mcp-http-to-stdio",
      "args": [
        "--url",
        "http://localhost:8080/mcp"
      ],
      "env": {
        "AUTH_TOKEN": "your-auth-token-here"
      }
    }
  }
}

Remote Server Configuration

{
  "mcpServers": {
    "remote-mcp-server": {
      "command": "mcp-http-to-stdio",
      "args": [
        "--url",
        "https://mcp-server.example.com/mcp"
      ],
      "env": {
        "AUTH_TOKEN": "your-auth-token-here"
      }
    }
  }
}

Configuration with Timeout

{
  "mcpServers": {
    "my-http-mcp-server": {
      "command": "mcp-http-to-stdio",
      "args": [
        "--url",
        "http://localhost:8080/mcp",
        "--timeout",
        "600"
      ],
      "env": {
        "AUTH_TOKEN": "your-auth-token-here"
      }
    }
  }
}

Command Line Arguments

mcp-http-to-stdio --help

Required Arguments

• --url: HTTP MCP server endpoint URL (e.g., http://localhost:8080/mcp)

Optional Arguments

• --share-key: Authentication key (alternative to environment variable)
• --timeout: Request timeout in seconds (default: 300 = 5 minutes)

Authentication

Authentication tokens can be passed via:

• Environment variable (recommended): Set in the env section of Claude Desktop config
• Command line argument: Use --share-key flag

The bridge adds the authentication token to the x-ally-share-key HTTP header when making requests to the MCP server.

Usage

• Install the bridge: pip install mcp-http-to-stdio
• Configure Claude Desktop with your HTTP MCP server URL
• Restart Claude Desktop to load the new MCP server
• Verify: Ask Claude "What MCP tools are available?"

Logging

Logs are written to two locations:

• Log file: mcp_http_to_stdio.log (in the current directory)
• stderr: Visible in Claude Desktop's developer console

View Logs

# Follow log file
tail -f mcp_http_to_stdio.log

# View Claude Desktop logs
# Enable developer mode in Claude Desktop settings
# Open developer console and look for MCP-related messages

Troubleshooting

"Connection refused" or "Failed to connect"

Cause: HTTP MCP server is not running or URL is incorrect

Solution:

• Verify the MCP server is running
• Check the URL in your configuration
• Test the endpoint with curl: curl http://localhost:8080/mcp

"Authentication failed" or 401/403 errors

Cause: Authentication token is missing, incorrect, or expired

Solution:

• Verify the auth token is correct in the env section
• Check if the token has expired
• Regenerate the token if necessary

Claude Desktop doesn't see the MCP server

Cause: Configuration file is malformed or in wrong location

Solution:

• Validate JSON syntax at https://jsonlint.com
• Verify file location matches your operating system
• Restart Claude Desktop after making changes
• Check Claude Desktop logs for MCP initialization errors

Slow response times

Cause: MCP server queries can take time, especially for complex operations

Expected behavior:

• Simple queries: <10 seconds
• Complex queries: 10-60 seconds
• Very complex queries: 60+ seconds (consider increasing timeout)

The bridge logs warnings for requests taking longer than 10 seconds.

Supported MCP Methods

The bridge supports all standard MCP JSON-RPC methods:

• initialize: Protocol handshake
• tools/list: List available tools
• tools/call: Execute a tool
• Notifications: Properly handles JSON-RPC notifications (no response expected)

Technical Details

Protocol Flow

• Claude Desktop sends JSON-RPC request via stdin
• Bridge forwards request to HTTP MCP server via POST
• HTTP MCP server processes request and returns JSON-RPC response
• Bridge forwards response back to Claude Desktop via stdout

HTTP Request Format

POST /mcp HTTP/1.1
Host: localhost:8080
x-ally-share-key: <auth-token>
Content-Type: application/json

{"jsonrpc": "2.0", "method": "tools/list", "id": 1}

Connection Pooling

The bridge uses optimized HTTP connection pooling:

• Keep-alive: Connections are reused
• Retry logic: Automatic retry on transient errors (429, 500-504)
• Pool size: 10 cached connections
• Backoff: Exponential backoff (1s, 2s, 4s)

Example: MyAlly Share Server

This bridge was originally created for MyAlly's workspace sharing feature. Here's an example configuration:

{
  "mcpServers": {
    "myally-workspace": {
      "command": "mcp-http-to-stdio",
      "args": [
        "--url",
        "http://localhost:8081/share/mcp"
      ],
      "env": {
        "ALLY_SHARE_KEY": "ally_share_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

For MyAlly-specific documentation, see the MyAlly repository.

Security Considerations

• Protect authentication tokens: Treat them like passwords
• Use environment variables: Don't hardcode tokens in config files
• Use HTTPS: For production deployments, always use HTTPS URLs
• Rotate tokens: Regularly regenerate authentication tokens
• Don't commit tokens: Never commit tokens to version control

Contributing

Contributions are welcome! This is a simple bridge utility, but improvements to error handling, logging, or protocol support are always appreciated.

License

MIT License - See LICENSE file for details

Links

• PyPI: https://pypi.org/project/mcp-http-to-stdio/
• GitHub: https://github.com/your-org/agentic-enterprise
• MCP Specification: https://modelcontextprotocol.io/