mcp2http

# MCP2HTTP

A minimal transport adapter for connecting stdio MCP clients to stateless HTTP MCP servers.

## Overview

MCP2HTTP enables Model Context Protocol clients using stdio transport to communicate with MCP servers over stateless HTTP. While MCP typically uses either stdio (for local processes) or Server-Sent Events (SSE) transport, this adapter bridges to regular HTTP endpoints, enabling new integration possibilities.

The adapter only handles basic transport layer conversion while providing optional state tracking through a client-generated UUID `Session-Id` header. It preserves protocol semantics, allowing clients and servers to interact directly without the need for SSE, thus working seamlessly with serverless platforms and legacy systems.

## Usage

Configure your MCP client to call this command with arguments in this format:

npx -y mcp2http  ["Header: Value"...]

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

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

You may additionally include any number of HTTP headers as arguments. For example, to include an auth token:

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

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

## Features

### Client-Generated Session Tracking

The adapter automatically generates a UUID and includes it as a `Session-Id` header with each request. While having clients generate session IDs might seem counterintuitive, this aspect resembles a 1996 proposal for `Session-Id` never formally adopted into HTTP standards. This mechanism offers remarkable simplicity and is intended to complement (not replace) proper authentication.

The 128-bit hex UUID format provides collision resistance and leverages a ubiquitous identifier standard, making it ideal for correlating requests in stateless HTTP environments. To prevent fragmentation and ensure consistent behavior, server implementations conforming with this design should reject non-128-bit hex `Session-Id` values (with or without dashes).

Servers can safely ignore the `Session-Id` header entirely if they don't need session tracking. This feature is optional and provided as a convenience for implementations that want correlation between requests without additional complexity.

### Capability Filtering

The adapter tracks server capabilities from the `initialize` response and blocks requests for unsupported capabilities. This feature addresses an issue with some MCP clients that repeatedly poll for unadvertised capabilities several times per minute. By filtering these requests before they reach the server, this adapter reduces unnecessary load when a server only supports specific capabilities, i.e. `tools`, while the client silently continues its polling behavior.

### Notification Handling

Notifications (messages with no ID) are silently dropped. This approach naturally aligns with HTTP's request/response architecture. When implementing MCP over stateless HTTP, dropping notifications emerges as a sensible choice, a conclusion reached by other implementations like the mcp-golang HTTP transport. While `notifications/initialized` may give pause, the practical benefits of consistent notification handling should triumph. Nevertheless, HTTP MCP servers may still desire to handle notifications gracefully, in case other implementations do forward them.

## License

MIT