Mcp2http

🚀 MCP2HTTP

A minimal transport adapter that connects MCP clients using standard input/output (stdio) to stateless HTTP MCP servers.

🚀 Quick Start

MCP2HTTP enables Model Context Protocol clients to establish a connection with an MCP server using HTTP communication through stdio transport. Although MCP typically uses stdio (for local processes) or Server-Sent Events (SSE) transport, this adapter can bridge them to regular HTTP endpoints, enabling new integration possibilities.

This adapter only handles basic transport layer conversions and provides optional state tracking through the Session-Id header with a unique identifier generated by the client. It preserves the protocol semantics, allowing the client and server to interact directly without using SSE, so it can work seamlessly with serverless platforms and legacy systems.

💻 Usage Examples

Basic Usage

Configure your MCP client to call this command in the following format:

npx -y mcp2http <endpoint-url> ["Header: Value"...]

For example, in the Claude Desktop configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "mcp2http",
        "http://localhost:3000/mcp"
      ]
    }
  }
}

You can also add any number of HTTP headers as parameters. For example, to include an authentication token:

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "mcp2http",
        "https://example.com/mcp",
        "Authorization: Bearer token123"
      ]
    }
  }
}

⚠️ Important Note

You need a fully functional MCP HTTP endpoint. An example server will be provided soon.

✨ Features

Client-Generated Session Tracking

The adapter automatically generates a unique identifier (UUID) and includes it as the Session-Id header in each request. Although it may seem counterintuitive for the client to generate the session ID, this approach is similar to the Session-Id proposal put forward in 1996 (which was never officially incorporated into the HTTP standard). This mechanism offers excellent simplicity and is designed to complement (rather than replace) proper authentication.

The 128-bit hexadecimal UUID format provides collision resistance and leverages a universal identifier standard, making it ideal for associating requests in a stateless HTTP environment. To prevent fragmentation and ensure consistent behavior, server implementations conforming to this design should reject non-128-bit hexadecimal Session-Id values (with or without dashes). If session tracking is not required, the server can completely ignore the Session-Id header. This feature is optional and serves as a convenience for implementations that only need correlation between requests without additional complexity.

Capability Filtering

The adapter records the server's capabilities from the initialize response and blocks requests for undeclared capabilities. This feature addresses the issue where some MCP clients repeatedly poll for unadvertised capabilities multiple times per minute. By filtering requests before they reach the server, the adapter reduces unnecessary load when the server only supports specific features (such as tools) while the client continues its silent polling behavior.

Notification Handling

Messages without an ID (notifications) are silently discarded. This approach naturally aligns with the request/response architecture of HTTP. When MCP is implemented over stateless HTTP, discarding notifications becomes a reasonable choice, a conclusion reached by other implementations such as the mcp-golang HTTP transport. Although notifications/initialized may be of concern, the practical benefits of consistency in handling notifications should prevail. However, an HTTP MCP server may still want to handle notifications gracefully in case other implementations do forward them.

📄 License

MIT