mcp-http-transport

HTTP/SSE transport for MCP servers with hot reload support

🎯 Problem Solved

When developing MCP servers, every code change requires restarting Claude Desktop. This breaks:

• ❌ Your conversation context
• ❌ Your development flow
• ❌ Your productivity (>1 minute per iteration)

With mcp-http-transport:

• ✅ Hot reload without Claude Desktop restart
• ✅ Automatic reconnection on server restart
• ✅ Development cycle < 5 seconds
• ✅ Zero modification to your MCP handlers

🚀 Quick Start

Installation

pip install mcp-http-transport

Basic Usage

import os
from mcp.server import Server
from mcp_http_transport import MCPTransportManager

# Your existing MCP server
server = Server("my-mcp-server")

@server.list_tools()
async def list_tools():
    return [...]  # Your tools

@server.call_tool()
async def call_tool(name, arguments):
    return [...]  # Your handlers

# Add transport layer (NO changes to handlers!)
async def main():
    transport = MCPTransportManager(
        server=server,
        transport_mode=os.getenv("MCP_TRANSPORT", "stdio"),
        host=os.getenv("MCP_HTTP_HOST", "localhost"),
        port=int(os.getenv("MCP_HTTP_PORT", "3000")),
    )
    await transport.start()

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

Configuration

.env file:

# Transport mode: "stdio" (default) or "http"
MCP_TRANSPORT=http
MCP_HTTP_HOST=localhost
MCP_HTTP_PORT=3000

Claude Desktop config:

{
  "mcpServers": {
    "my-server": {
      "url": "http://localhost:3000/sse"
    }
  }
}

That's it! Now when you modify your code:

1. Watchdog detects change → restarts server
2. Claude Desktop reconnects automatically
3. No manual restart needed!

📚 Documentation

Transport Modes

Mode	Use Case	Pros	Cons
stdio (default)	Production	Simple, minimal overhead	No hot reload
http	Development	Hot reload, auto-reconnect	Requires port

Environment Variables

• MCP_TRANSPORT: "stdio" or "http" (default: "stdio")
• MCP_HTTP_HOST: HTTP server host (default: "localhost")
• MCP_HTTP_PORT: HTTP server port (default: 3000)

With Watchdog (Hot Reload)

Install watchdog:

pip install watchdog

Create wrapper script (mcp-server-wrapper.sh):

#!/bin/bash
cd /path/to/your/project

if [ "$MCP_DEV_MODE" = "1" ]; then
    echo "[MCP] Dev mode - auto-reload enabled"
    exec python -m watchdog.watchmedo auto-restart \
        -d your_package \
        -p "*.py" \
        -R \
        --interval 1.0 \
        --debounce-interval 0.5 \
        -- python -m your_package.mcp_server
else
    exec python -m your_package.mcp_server
fi

Claude Desktop config:

{
  "mcpServers": {
    "my-server": {
      "command": "/path/to/mcp-server-wrapper.sh",
      "env": {
        "MCP_DEV_MODE": "1",
        "MCP_TRANSPORT": "http",
        "MCP_HTTP_PORT": "3000"
      }
    }
  }
}

🏗️ Architecture

┌─────────────────┐
│ Claude Desktop  │
└────────┬────────┘
         │
         ├─── stdio (default)
         │    └─> stdin/stdout pipes
         │
         └─── http (dev)
              ├─> GET /sse (Server-Sent Events)
              └─> POST /messages/ (JSON-RPC)

HTTP/SSE Flow:

1. Client: GET http://localhost:3000/sse → establishes SSE stream
2. Client: POST http://localhost:3000/messages/ → sends JSON-RPC requests
3. Server: responds via SSE stream
4. Watchdog restarts server → Client reconnects automatically

🔧 Advanced Usage

Multiple MCP Servers

Run multiple MCP servers on different ports:

{
  "mcpServers": {
    "server-1": {
      "url": "http://localhost:3000/sse"
    },
    "server-2": {
      "url": "http://localhost:3001/sse"
    }
  }
}

Custom Host/Port

transport = MCPTransportManager(
    server=server,
    transport_mode="http",
    host="0.0.0.0",  # Listen on all interfaces
    port=8080,
)

Switching Back to Stdio

Just remove or change the environment variable:

# Back to stdio (production)
MCP_TRANSPORT=stdio

Or omit it entirely (defaults to stdio).

🧪 Testing

# Install dev dependencies
pip install mcp-http-transport[dev]

# Run tests
pytest

# With coverage
pytest --cov=mcp_http_transport

🤝 Contributing

Contributions welcome! This package was extracted from a real-world MCP server to benefit the community.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🙏 Credits

• Built for MCP (Model Context Protocol)
• Inspired by real-world pain points in MCP development
• Uses Starlette and Uvicorn

⚠️ Known Issues (v0.2.0)

Compatibility with mcp-remote

Status: The HTTP/SSE server implementation is not yet fully compatible with mcp-remote (the official Node.js proxy).

Symptoms:

• mcp-remote fails with SSE header errors
• POST endpoint works (HTTP 202) but connection drops

Workaround:

1. Use stdio transport (default) for Claude Desktop
2. Use mcp-stdio-proxy (Python) when available
3. Or implement your own client that follows MCP HTTP/SSE spec

Contributing: We welcome PRs to fix compatibility! See the repository for details.

---

🐛 Troubleshooting

Port Already in Use

# Find process using port
lsof -ti:3000

# Kill process
lsof -ti:3000 | xargs kill -9

# Or use different port
MCP_HTTP_PORT=3001

Claude Desktop Not Reconnecting

Cause: SSE retry delay (2-5s is normal)

Solution: Wait a few seconds after server restart. Claude Desktop will show "Reconnecting..." then connect automatically.

HTTP Mode Not Working

Check:

1. Server logs: tail -f /tmp/mcp-server-debug.log
2. Test endpoint: curl http://localhost:3000/sse
3. Verify Claude Desktop config has correct URL

📊 Comparison

Feature	stdio	http
Setup	Simple	Medium
Hot Reload	❌	✅
Auto-Reconnect	❌	✅
Production Ready	✅	⚠️ Dev only
Multi-client	❌	✅
Overhead	Minimal	Very Low

---

Made with ❤️ for the MCP community

If this package saves you time, consider ⭐ starring the repo!