streamable http mcp

.gitignore

@@ -194,3 +194,5 @@ docs/superpowers/
 
 # Managed platform (separate private repo)
 headroom-managed/
+
+context/

README.md

@@ -197,7 +197,22 @@ Compress what moves between agents — any framework. **[SharedContext Guide](do
 headroom mcp install && claude
 ```
 
-Gives your AI tool three MCP tools: `headroom_compress`, `headroom_retrieve`, `headroom_stats`. **[MCP Guide](docs/mcp.md)**
+Gives your AI tool three MCP tools: `headroom_compress`, `headroom_retrieve`, `headroom_stats`.
+
+**Remote agents (Docker, network):**
+
+```bash
+# Proxy auto-exposes MCP at /mcp via Streamable HTTP
+headroom proxy                                          # → http://host:8787/mcp
+
+# Or standalone MCP server
+headroom mcp serve --transport http --port 8080         # → http://host:8080/mcp
+
+# Configure remote agent
+headroom mcp install --remote http://proxy-host:8787/mcp
+```
+
+**[MCP Guide](docs/mcp.md)**
 
 ### Drop into your existing stack
 
@@ -420,7 +435,8 @@ Context compression is a new space. Here's how the approaches differ:
 | ASGI middleware | **Stable** | [Integration Guide](docs/integration-guide.md#asgi-middleware) |
 | Proxy server | **Stable** | [Proxy Docs](docs/proxy.md) |
 | Agno | **Stable** | [Agno Guide](docs/agno.md) |
-| MCP (Claude Code, Cursor, etc.) | **Stable** | [MCP Guide](docs/mcp.md) |
+| MCP — stdio (local) | **Stable** | [MCP Guide](docs/mcp.md) |
+| MCP — Streamable HTTP (remote/Docker) | **Stable** | [MCP Guide](docs/mcp.md) |
 | Strands | **Stable** | [Strands Guide](docs/strands.md) |
 | LangChain | **Stable** | [LangChain Guide](docs/langchain.md) |
 | **OpenClaw** | **Stable** | [OpenClaw plugin](#openclaw-plugin) |

docs/content/docs/mcp.mdx

@@ -99,32 +99,97 @@ Session compression statistics.
 
 Sub-agent stats are aggregated via a shared stats file at `~/.headroom/session_stats.jsonl`.
 
+## Streamable HTTP Transport (Remote / Docker)
+
+For agents running on a different machine than the Headroom proxy (e.g., Docker, cloud), MCP tools are available over HTTP using the MCP Streamable HTTP protocol.
+
+### Proxy auto-exposes /mcp
+
+When you run `headroom proxy`, MCP tools are automatically available at `/mcp`:
+
+```bash
+headroom proxy  # → http://host:8787/mcp
+```
+
+Remote agents connect with:
+
+```json
+{
+  "mcpServers": {
+    "headroom": {
+      "url": "http://proxy-host:8787/mcp"
+    }
+  }
+}
+```
+
+### Standalone HTTP server
+
+Run MCP tools without the full proxy:
+
+```bash
+headroom mcp serve --transport http --port 8080
+```
+
+### Remote install
+
+Configure Claude Code to use remote MCP over HTTP:
+
+```bash
+headroom mcp install --remote http://proxy-host:8787/mcp
+```
+
+This writes URL-based config instead of the default command-based config.
+
+### Protocol
+
+The Streamable HTTP transport implements the MCP specification:
+- `POST /mcp` -- Send JSON-RPC requests (tool calls, list tools)
+- `GET /mcp` -- Server-sent events stream (server-initiated messages)
+- `DELETE /mcp` -- Terminate session
+
+Stateless mode by default -- each request is independent, no session tracking needed.
+
 ## CLI commands
 
 ```bash
-# Install (registers with Claude Code)
+# Install — local (stdio, default)
 headroom mcp install
-headroom mcp install --proxy-url http://host:9000  # Custom proxy URL
-headroom mcp install --force                        # Overwrite existing
+
+# Install — remote (HTTP, for Docker/network)
+headroom mcp install --remote http://proxy-host:8787/mcp
+
+# Install — custom proxy URL
+headroom mcp install --proxy-url http://host:9000
+
+# Overwrite existing config
+headroom mcp install --force
+
+# Serve — stdio (default, called by Claude Code)
+headroom mcp serve
+
+# Serve — HTTP (for remote agents)
+headroom mcp serve --transport http --port 8080
+
+# Serve — debug mode
+headroom mcp serve --debug
 
 # Check status
 headroom mcp status
 
 # Uninstall
 headroom mcp uninstall
-
-# Debug mode
-headroom mcp serve --debug
 ```
 
 ## Cross-tool compatibility
 
-| Tool | MCP Support | Setup |
-|------|-------------|-------|
-| Claude Code | Native | `headroom mcp install` |
-| Cursor | Supported | Add to Cursor MCP settings |
-| Codex | If supported | Configure MCP server |
-| Any MCP host | Yes | Point to `headroom mcp serve` |
+| Tool | Transport | Setup |
+|------|-----------|-------|
+| Claude Code (local) | stdio | `headroom mcp install` |
+| Claude Code (remote) | HTTP | `headroom mcp install --remote http://host:8787/mcp` |
+| Cursor | stdio / HTTP | Add to MCP settings |
+| Docker agents | HTTP | Point to `http://proxy:8787/mcp` |
+| Any MCP host | stdio / HTTP | `headroom mcp serve` or `--transport http` |
 
 ## Architecture
 
@@ -138,6 +203,22 @@ The proxy compresses all traffic at the HTTP level (before the LLM sees content)
 
 `headroom_retrieve` checks the local store first, then falls back to the proxy's store.
 
+### Remote (HTTP transport)
+
+```
+Remote Agent (any machine)
+    |
+    | POST /mcp (JSON-RPC)
+    v
+Headroom Proxy :8787/mcp (Streamable HTTP)
+    |
+    | in-process access
+    v
+Compression Pipeline + CompressionStore
+```
+
+The proxy's `/mcp` endpoint shares the same compression store and pipeline as the proxy itself -- no HTTP round-trips to self.
+
 ## Troubleshooting
 
 **"MCP SDK not installed"** -- Run `pip install "headroom-ai[mcp]"`.