# 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)
```bash
pip install mcp-http-to-stdio
```
This installs the package globally and makes the `mcp-http-to-stdio` command available system-wide.
### From Source
```bash
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
```json
{
"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
```json
{
"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
```json
{
"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
```bash
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:
1. **Environment variable** (recommended): Set in the `env` section of Claude Desktop config
2. **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
1. **Install** the bridge: `pip install mcp-http-to-stdio`
2. **Configure** Claude Desktop with your HTTP MCP server URL
3. **Restart** Claude Desktop to load the new MCP server
4. **Verify**: Ask Claude "What MCP tools are available?"
## Logging
Logs are written to two locations:
1. **Log file**: `mcp_http_to_stdio.log` (in the current directory)
2. **stderr**: Visible in Claude Desktop's developer console
### View Logs
```bash
# 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**:
1. Verify the MCP server is running
2. Check the URL in your configuration
3. 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**:
1. Verify the auth token is correct in the `env` section
2. Check if the token has expired
3. Regenerate the token if necessary
### Claude Desktop doesn't see the MCP server
**Cause**: Configuration file is malformed or in wrong location
**Solution**:
1. Validate JSON syntax at https://jsonlint.com
2. Verify file location matches your operating system
3. Restart Claude Desktop after making changes
4. 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:
1. **`initialize`**: Protocol handshake
2. **`tools/list`**: List available tools
3. **`tools/call`**: Execute a tool
4. **Notifications**: Properly handles JSON-RPC notifications (no response expected)
## Technical Details
### Protocol Flow
1. Claude Desktop sends JSON-RPC request via stdin
2. Bridge forwards request to HTTP MCP server via POST
3. HTTP MCP server processes request and returns JSON-RPC response
4. Bridge forwards response back to Claude Desktop via stdout
### HTTP Request Format
```http
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:
```json
{
"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](https://github.com/your-org/agentic-enterprise).
## 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/
Raw data
{
"_id": null,
"home_page": null,
"name": "mcp-http-to-stdio",
"maintainer": "Agentic Enterprise",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "mcp, model-context-protocol, claude, claude-desktop, anthropic, http, stdio, bridge, proxy, json-rpc, protocol-bridge",
"author": "Agentic Enterprise",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/ee/79/215fcd646d57f619f0af9e6b526129041b21911dad64c0f8fb61ce2d7523/mcp_http_to_stdio-0.1.1.tar.gz",
"platform": null,
"description": "# MCP HTTP-to-STDIO Bridge\r\n\r\nA Python bridge utility that enables Claude Desktop to connect to HTTP-based MCP (Model Context Protocol) servers via stdio transport.\r\n\r\n## Overview\r\n\r\nClaude 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.\r\n\r\n**Architecture:**\r\n```\r\nClaude Desktop (stdio/JSON-RPC) \u2190\u2192 mcp-http-to-stdio (bridge) \u2190\u2192 HTTP MCP Server\r\n```\r\n\r\n## Features\r\n\r\n- \u2705 **Protocol Translation**: Converts stdio JSON-RPC to HTTP POST requests\r\n- \u2705 **Authentication**: Supports custom header-based authentication\r\n- \u2705 **Connection Pooling**: Optimized HTTP connections with keep-alive and retry logic\r\n- \u2705 **Error Handling**: Comprehensive error responses for network, auth, and server errors\r\n- \u2705 **Logging**: File and stderr logging for debugging\r\n- \u2705 **Performance**: Tracks request timing and logs slow requests\r\n\r\n## Prerequisites\r\n\r\n- Python 3.8+\r\n- An HTTP-based MCP server to connect to\r\n- Claude Desktop\r\n\r\n## Installation\r\n\r\n### From PyPI (Recommended)\r\n\r\n```bash\r\npip install mcp-http-to-stdio\r\n```\r\n\r\nThis installs the package globally and makes the `mcp-http-to-stdio` command available system-wide.\r\n\r\n### From Source\r\n\r\n```bash\r\ngit clone https://github.com/your-org/agentic-enterprise.git\r\ncd agentic-enterprise/packages/mcp-http-to-stdio\r\npip install -e .\r\n```\r\n\r\n## Configuration\r\n\r\n### Claude Desktop Config File Location\r\n\r\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\r\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\r\n- **Linux**: `~/.config/Claude/claude_desktop_config.json`\r\n\r\n### Basic Configuration\r\n\r\n```json\r\n{\r\n \"mcpServers\": {\r\n \"my-http-mcp-server\": {\r\n \"command\": \"mcp-http-to-stdio\",\r\n \"args\": [\r\n \"--url\",\r\n \"http://localhost:8080/mcp\"\r\n ],\r\n \"env\": {\r\n \"AUTH_TOKEN\": \"your-auth-token-here\"\r\n }\r\n }\r\n }\r\n}\r\n```\r\n\r\n### Remote Server Configuration\r\n\r\n```json\r\n{\r\n \"mcpServers\": {\r\n \"remote-mcp-server\": {\r\n \"command\": \"mcp-http-to-stdio\",\r\n \"args\": [\r\n \"--url\",\r\n \"https://mcp-server.example.com/mcp\"\r\n ],\r\n \"env\": {\r\n \"AUTH_TOKEN\": \"your-auth-token-here\"\r\n }\r\n }\r\n }\r\n}\r\n```\r\n\r\n### Configuration with Timeout\r\n\r\n```json\r\n{\r\n \"mcpServers\": {\r\n \"my-http-mcp-server\": {\r\n \"command\": \"mcp-http-to-stdio\",\r\n \"args\": [\r\n \"--url\",\r\n \"http://localhost:8080/mcp\",\r\n \"--timeout\",\r\n \"600\"\r\n ],\r\n \"env\": {\r\n \"AUTH_TOKEN\": \"your-auth-token-here\"\r\n }\r\n }\r\n }\r\n}\r\n```\r\n\r\n## Command Line Arguments\r\n\r\n```bash\r\nmcp-http-to-stdio --help\r\n```\r\n\r\n### Required Arguments\r\n\r\n- `--url`: HTTP MCP server endpoint URL (e.g., `http://localhost:8080/mcp`)\r\n\r\n### Optional Arguments\r\n\r\n- `--share-key`: Authentication key (alternative to environment variable)\r\n- `--timeout`: Request timeout in seconds (default: 300 = 5 minutes)\r\n\r\n### Authentication\r\n\r\nAuthentication tokens can be passed via:\r\n1. **Environment variable** (recommended): Set in the `env` section of Claude Desktop config\r\n2. **Command line argument**: Use `--share-key` flag\r\n\r\nThe bridge adds the authentication token to the `x-ally-share-key` HTTP header when making requests to the MCP server.\r\n\r\n## Usage\r\n\r\n1. **Install** the bridge: `pip install mcp-http-to-stdio`\r\n2. **Configure** Claude Desktop with your HTTP MCP server URL\r\n3. **Restart** Claude Desktop to load the new MCP server\r\n4. **Verify**: Ask Claude \"What MCP tools are available?\"\r\n\r\n## Logging\r\n\r\nLogs are written to two locations:\r\n\r\n1. **Log file**: `mcp_http_to_stdio.log` (in the current directory)\r\n2. **stderr**: Visible in Claude Desktop's developer console\r\n\r\n### View Logs\r\n\r\n```bash\r\n# Follow log file\r\ntail -f mcp_http_to_stdio.log\r\n\r\n# View Claude Desktop logs\r\n# Enable developer mode in Claude Desktop settings\r\n# Open developer console and look for MCP-related messages\r\n```\r\n\r\n## Troubleshooting\r\n\r\n### \"Connection refused\" or \"Failed to connect\"\r\n\r\n**Cause**: HTTP MCP server is not running or URL is incorrect\r\n\r\n**Solution**:\r\n1. Verify the MCP server is running\r\n2. Check the URL in your configuration\r\n3. Test the endpoint with curl: `curl http://localhost:8080/mcp`\r\n\r\n### \"Authentication failed\" or 401/403 errors\r\n\r\n**Cause**: Authentication token is missing, incorrect, or expired\r\n\r\n**Solution**:\r\n1. Verify the auth token is correct in the `env` section\r\n2. Check if the token has expired\r\n3. Regenerate the token if necessary\r\n\r\n### Claude Desktop doesn't see the MCP server\r\n\r\n**Cause**: Configuration file is malformed or in wrong location\r\n\r\n**Solution**:\r\n1. Validate JSON syntax at https://jsonlint.com\r\n2. Verify file location matches your operating system\r\n3. Restart Claude Desktop after making changes\r\n4. Check Claude Desktop logs for MCP initialization errors\r\n\r\n### Slow response times\r\n\r\n**Cause**: MCP server queries can take time, especially for complex operations\r\n\r\n**Expected behavior**:\r\n- Simple queries: <10 seconds\r\n- Complex queries: 10-60 seconds\r\n- Very complex queries: 60+ seconds (consider increasing timeout)\r\n\r\nThe bridge logs warnings for requests taking longer than 10 seconds.\r\n\r\n## Supported MCP Methods\r\n\r\nThe bridge supports all standard MCP JSON-RPC methods:\r\n\r\n1. **`initialize`**: Protocol handshake\r\n2. **`tools/list`**: List available tools\r\n3. **`tools/call`**: Execute a tool\r\n4. **Notifications**: Properly handles JSON-RPC notifications (no response expected)\r\n\r\n## Technical Details\r\n\r\n### Protocol Flow\r\n\r\n1. Claude Desktop sends JSON-RPC request via stdin\r\n2. Bridge forwards request to HTTP MCP server via POST\r\n3. HTTP MCP server processes request and returns JSON-RPC response\r\n4. Bridge forwards response back to Claude Desktop via stdout\r\n\r\n### HTTP Request Format\r\n\r\n```http\r\nPOST /mcp HTTP/1.1\r\nHost: localhost:8080\r\nx-ally-share-key: <auth-token>\r\nContent-Type: application/json\r\n\r\n{\"jsonrpc\": \"2.0\", \"method\": \"tools/list\", \"id\": 1}\r\n```\r\n\r\n### Connection Pooling\r\n\r\nThe bridge uses optimized HTTP connection pooling:\r\n\r\n- **Keep-alive**: Connections are reused\r\n- **Retry logic**: Automatic retry on transient errors (429, 500-504)\r\n- **Pool size**: 10 cached connections\r\n- **Backoff**: Exponential backoff (1s, 2s, 4s)\r\n\r\n## Example: MyAlly Share Server\r\n\r\nThis bridge was originally created for MyAlly's workspace sharing feature. Here's an example configuration:\r\n\r\n```json\r\n{\r\n \"mcpServers\": {\r\n \"myally-workspace\": {\r\n \"command\": \"mcp-http-to-stdio\",\r\n \"args\": [\r\n \"--url\",\r\n \"http://localhost:8081/share/mcp\"\r\n ],\r\n \"env\": {\r\n \"ALLY_SHARE_KEY\": \"ally_share_xxxxxxxxxxxxxxxx\"\r\n }\r\n }\r\n }\r\n}\r\n```\r\n\r\nFor MyAlly-specific documentation, see the [MyAlly repository](https://github.com/your-org/agentic-enterprise).\r\n\r\n## Security Considerations\r\n\r\n- **Protect authentication tokens**: Treat them like passwords\r\n- **Use environment variables**: Don't hardcode tokens in config files\r\n- **Use HTTPS**: For production deployments, always use HTTPS URLs\r\n- **Rotate tokens**: Regularly regenerate authentication tokens\r\n- **Don't commit tokens**: Never commit tokens to version control\r\n\r\n## Contributing\r\n\r\nContributions are welcome! This is a simple bridge utility, but improvements to error handling, logging, or protocol support are always appreciated.\r\n\r\n## License\r\n\r\nMIT License - See LICENSE file for details\r\n\r\n## Links\r\n\r\n- **PyPI**: https://pypi.org/project/mcp-http-to-stdio/\r\n- **GitHub**: https://github.com/your-org/agentic-enterprise\r\n- **MCP Specification**: https://modelcontextprotocol.io/\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Bridge utility enabling Claude Desktop to connect to HTTP-based MCP servers via stdio transport",
"version": "0.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/agentic-enterprise/mcp-http-to-stdio/issues",
"Documentation": "https://github.com/agentic-enterprise/mcp-http-to-stdio#readme",
"Homepage": "https://github.com/agentic-enterprise/mcp-http-to-stdio",
"Repository": "https://github.com/agentic-enterprise/mcp-http-to-stdio"
},
"split_keywords": [
"mcp",
" model-context-protocol",
" claude",
" claude-desktop",
" anthropic",
" http",
" stdio",
" bridge",
" proxy",
" json-rpc",
" protocol-bridge"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e746ba5f9f779cc01aeef8d6e47e870d2264f2c0943ddbb19a8d12d2710809cd",
"md5": "74d0510697dfaa8c66f089774c251646",
"sha256": "fb50112a5ce4a83ce8005a1793941feb8754c7734f131386f0ef8e2e0e57c41f"
},
"downloads": -1,
"filename": "mcp_http_to_stdio-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "74d0510697dfaa8c66f089774c251646",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 9311,
"upload_time": "2025-11-03T15:27:48",
"upload_time_iso_8601": "2025-11-03T15:27:48.393816Z",
"url": "https://files.pythonhosted.org/packages/e7/46/ba5f9f779cc01aeef8d6e47e870d2264f2c0943ddbb19a8d12d2710809cd/mcp_http_to_stdio-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ee79215fcd646d57f619f0af9e6b526129041b21911dad64c0f8fb61ce2d7523",
"md5": "791a0206ee8df0fbd4f47bf51710c172",
"sha256": "a89be66163ffcfae2689347e0d0d30b5a60493d67cce525ca1a257645f17482d"
},
"downloads": -1,
"filename": "mcp_http_to_stdio-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "791a0206ee8df0fbd4f47bf51710c172",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 10079,
"upload_time": "2025-11-03T15:27:49",
"upload_time_iso_8601": "2025-11-03T15:27:49.620021Z",
"url": "https://files.pythonhosted.org/packages/ee/79/215fcd646d57f619f0af9e6b526129041b21911dad64c0f8fb61ce2d7523/mcp_http_to_stdio-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-03 15:27:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "agentic-enterprise",
"github_project": "mcp-http-to-stdio",
"github_not_found": true,
"lcname": "mcp-http-to-stdio"
}
JSON
