Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

feat(mcp): add streamable HTTP MCP transport (#1773)

Rod Boev4ea96a417cee
diff --git a/docs/content/docs/mcp.mdx b/docs/content/docs/mcp.mdx
index bd6978fd2..af6302825 100644
--- a/docs/content/docs/mcp.mdx
+++ b/docs/content/docs/mcp.mdx
@@ -115,6 +115,9 @@ headroom mcp uninstall
# Debug mode
headroom mcp serve --debug
+
+# Streamable HTTP mode
+headroom mcp serve --transport http --host 127.0.0.1 --port 8788 --path /mcp
```
## MCP host configuration
@@ -154,7 +157,9 @@ For multiple proxy instances, register one stdio MCP server per proxy URL:
}
```
-Do not assume that a running proxy exposes an HTTP MCP endpoint at `/mcp`. If `http://127.0.0.1:<port>/mcp` returns `404`, use the stdio configuration above.
+If you need Streamable HTTP instead of stdio, run `headroom mcp serve --transport http` and point your MCP host at that endpoint. The default path is `/mcp`, and the default port is `8788`.
+
+Do not assume that a running proxy exposes an HTTP MCP endpoint at `/mcp`. The proxy serves its own API; it does not automatically provide the MCP HTTP transport.
### `command: "headroom"` fails to start
diff --git a/headroom/ccr/mcp_http.py b/headroom/ccr/mcp_http.py
new file mode 100644
index 000000000..eee5ab240
--- /dev/null
+++ b/headroom/ccr/mcp_http.py
@@ -0,0 +1,78 @@
+"""Streamable HTTP transport helpers for the Headroom MCP server."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
+from starlette.applications import Starlette
+from starlette.routing import Route
+from starlette.types import Receive, Scope, Send
+
+
+def _normalize_path(path: str) -> str:
+ normalized = path.strip()
+ if not normalized.startswith("/"):
+ normalized = f"/{normalized}"
+ if normalized != "/":
+ normalized = normalized.rstrip("/")
+ return normalized
+
+
+class StreamableHTTPASGIApp:
+ """Delegate ASGI requests to the SDK session manager."""
+
+ def __init__(self, session_manager: StreamableHTTPSessionManager):
+ self.session_manager = session_manager
+
+ async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+ await self.session_manager.handle_request(scope, receive, send)
+
+
+def create_streamable_http_session_manager(server: Any) -> StreamableHTTPSessionManager:
+ """Build the SDK session manager for an existing MCP server."""
+ return StreamableHTTPSessionManager(app=server.server)
+
+
+def create_streamable_http_app(
+ session_manager: StreamableHTTPSessionManager,
+ *,
+ path: str,
+ debug: bool = False,
+) -> Starlette:
+ """Build the Starlette app that exposes the MCP server over HTTP."""
+ streamable_http_app = StreamableHTTPASGIApp(session_manager)
+ return Starlette(
+ debug=debug,
+ routes=[
+ Route(
+ _normalize_path(path),
+ endpoint=streamable_http_app,
+ methods=["GET", "POST", "DELETE", "OPTIONS"],
+ )
+ ],
+ lifespan=lambda app: session_manager.run(),
+ )
+
+
+async def serve_streamable_http(
+ server: Any,
+ *,
+ host: str,
+ port: int,
+ path: str,
+ debug: bool = False,
+) -> None:
+ """Serve the MCP server over Streamable HTTP with uvicorn."""
+ import uvicorn
+
+ session_manager = create_streamable_http_session_manager(server)
+ starlette_app = create_streamable_http_app(session_manager, path=path, debug=debug)
+ config = uvicorn.Config(
+ starlette_app,
+ host=host,
+ port=port,
+ log_level="debug" if debug else "warning",
+ )
+ uvicorn_server = uvicorn.Server(config)
+ await uvicorn_server.serve()
diff --git a/headroom/ccr/mcp_server.py b/headroom/ccr/mcp_server.py
index aa8a2b4d4..f6f771af6 100644
--- a/headroom/ccr/mcp_server.py
+++ b/headroom/ccr/mcp_server.py
@@ -1046,6 +1046,24 @@ class HeadroomMCPServer:
self.server.create_initialization_options(),
)
+ async def run_streamable_http(
+ self,
+ host: str,
+ port: int,
+ path: str,
+ debug: bool = False,
+ ) -> None:
+ """Run the server with Streamable HTTP transport."""
+ from .mcp_http import serve_streamable_http
+
+ await serve_streamable_http(
+ self,
+ host=host,
+ port=port,
+ path=path,
+ debug=debug,
+ )
+
async def cleanup(self) -> None:
"""Clean up resources."""
if self._http_client:
diff --git a/headroom/cli/mcp.py b/headroom/cli/mcp.py
index bcef72e51..a9ea4228e 100644
--- a/headroom/cli/mcp.py
+++ b/headroom/cli/mcp.py
@@ -17,6 +17,9 @@ from .main import main
CLAUDE_CONFIG_DIR = Path.home() / ".claude"
MCP_CONFIG_PATH = CLAUDE_CONFIG_DIR / "mcp.json"
DEFAULT_PROXY_URL = "http://127.0.0.1:8787"
+DEFAULT_HTTP_HOST = "127.0.0.1"
+DEFAULT_HTTP_PORT = 8788
+DEFAULT_HTTP_PATH = "/mcp"
def get_headroom_command() -> list[str]:
@@ -257,6 +260,32 @@ def mcp_status() -> None:
envvar="HEADROOM_PROXY_URL",
help=f"Headroom proxy URL (default: {DEFAULT_PROXY_URL})",
)
+ "--transport",
+ type=click.Choice(["stdio", "http"], case_sensitive=False),
+ default="stdio",
+ show_default=True,
+ help="Transport to use for headroom mcp serve",
+)
+ "--host",
+ default=DEFAULT_HTTP_HOST,
+ show_default=True,
+ help="HTTP bind host",
+)
+ "--port",
+ default=DEFAULT_HTTP_PORT,
+ show_default=True,
+ type=int,
+ help="HTTP bind port",
+)
+ "--path",
+ default=DEFAULT_HTTP_PATH,
+ show_default=True,
+ help="HTTP endpoint path",
+)
@click.option(
"--direct",
is_flag=True,
@@ -267,16 +296,26 @@ def mcp_status() -> None:
is_flag=True,
help="Enable debug logging",
)
-def mcp_serve(proxy_url: str | None, direct: bool, debug: bool) -> None:
+def mcp_serve(
+ proxy_url: str | None,
+ transport: str,
+ host: str,
+ port: int,
+ path: str,
+ direct: bool,
+ debug: bool,
+) -> None:
"""Start the MCP server (called by Claude Code).
\b
This command is typically invoked by Claude Code via the MCP config,
- not run directly. It starts the MCP server with stdio transport.
+ not run directly. It starts the MCP server with stdio by default or
+ Streamable HTTP when requested.
\b
For manual testing:
headroom mcp serve --debug
+ headroom mcp serve --transport http --host 127.0.0.1 --port 8788 --path /mcp
"""
import asyncio
import logging
@@ -301,6 +340,8 @@ def mcp_serve(proxy_url: str | None, direct: bool, debug: bool) -> None:
format="%(levelname)s: %(message)s",
)
+ transport = transport.lower()
+
# Use default if not specified
effective_proxy_url = proxy_url or DEFAULT_PROXY_URL
@@ -314,7 +355,10 @@ def mcp_serve(proxy_url: str | None, direct: bool, debug: bool) -> None:
async def run() -> None:
try:
- await server.run_stdio()
+ if transport == "http":
+ await server.run_streamable_http(host=host, port=port, path=path, debug=debug)
+ else:
+ await server.run_stdio()
finally:
await server.cleanup()
diff --git a/pyproject.toml b/pyproject.toml
index 1a4d4878a..8ca011e14 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -212,6 +212,8 @@ strands = [
mcp = [
"mcp>=1.0.0",
"httpx>=0.24.0",
+ "starlette>=0.27.0",
+ "uvicorn>=0.23.0,<1.0",
]
# Voice filler detection
voice = [
diff --git a/tests/test_ccr_mcp_http.py b/tests/test_ccr_mcp_http.py
new file mode 100644
index 000000000..d7b49fa5f
--- /dev/null
+++ b/tests/test_ccr_mcp_http.py
@@ -0,0 +1,51 @@
+"""Contract tests for the Headroom Streamable HTTP MCP transport."""
+
+from __future__ import annotations
+
+import httpx
+import pytest
+
+pytest.importorskip("mcp")
+
+from mcp.client.session import ClientSession
+from mcp.client.streamable_http import streamable_http_client
+
+from headroom.ccr.mcp_http import (
+ create_streamable_http_app,
+ create_streamable_http_session_manager,
+)
+from headroom.ccr.mcp_server import create_ccr_mcp_server
+
+pytestmark = pytest.mark.anyio
+
+
+def anyio_backend() -> str:
+ return "asyncio"
+
+
+async def test_streamable_http_initialize_and_list_tools() -> None:
+ server = create_ccr_mcp_server()
+ session_manager = create_streamable_http_session_manager(server)
+ app = create_streamable_http_app(session_manager, path="/mcp")
+ transport = httpx.ASGITransport(app=app)
+
+ async with session_manager.run():
+ async with httpx.AsyncClient(
+ transport=transport, base_url="http://testserver"
+ ) as http_client:
+ async with streamable_http_client(
+ "http://testserver/mcp",
+ http_client=http_client,
+ terminate_on_close=False,
+ ) as (read_stream, write_stream, get_session_id):
+ async with ClientSession(read_stream, write_stream) as session:
+ initialize_result = await session.initialize()
+ list_tools_result = await session.list_tools()
+
+ tool_names = [tool.name for tool in list_tools_result.tools]
+ assert initialize_result.protocolVersion
+ assert get_session_id() is not None
+ assert "headroom_compress" in tool_names
+ assert "headroom_retrieve" in tool_names
+ assert "headroom_stats" in tool_names
diff --git a/tests/test_cli/test_mcp.py b/tests/test_cli/test_mcp.py
index 7048c271a..86f02994a 100644
--- a/tests/test_cli/test_mcp.py
+++ b/tests/test_cli/test_mcp.py
@@ -8,7 +8,7 @@ These are real tests that:
import json
import sys
-from unittest.mock import MagicMock, patch
+from unittest.mock import AsyncMock, MagicMock, patch
import pytest
from click.testing import CliRunner
@@ -240,9 +240,64 @@ class TestMCPServeCommand:
result = runner.invoke(main, ["mcp", "serve", "--help"])
assert result.exit_code == 0
+ assert "transport" in result.output
+ assert "host" in result.output
+ assert "port" in result.output
+ assert "path" in result.output
assert "proxy-url" in result.output
assert "debug" in result.output
+ def test_serve_defaults_to_stdio(self):
+ """Serve command defaults to stdio transport."""
+ fake_server = MagicMock()
+ fake_server.run_stdio = AsyncMock()
+ fake_server.run_streamable_http = AsyncMock()
+ fake_server.cleanup = AsyncMock()
+
+ runner = CliRunner()
+ with patch("headroom.ccr.mcp_server.create_ccr_mcp_server", return_value=fake_server):
+ result = runner.invoke(main, ["mcp", "serve"])
+
+ assert result.exit_code == 0
+ fake_server.run_stdio.assert_awaited_once()
+ fake_server.run_streamable_http.assert_not_awaited()
+ fake_server.cleanup.assert_awaited_once()
+
+ def test_serve_http_transport_uses_http_settings(self):
+ """Serve command uses HTTP transport when requested with mixed-case input."""
+ fake_server = MagicMock()
+ fake_server.run_stdio = AsyncMock()
+ fake_server.run_streamable_http = AsyncMock()
+ fake_server.cleanup = AsyncMock()
+
+ runner = CliRunner()
+ with patch("headroom.ccr.mcp_server.create_ccr_mcp_server", return_value=fake_server):
+ result = runner.invoke(
+ main,
+ [
+ "mcp",
+ "serve",
+ "--transport",
+ "HTTP",
+ "--host",
+ "0.0.0.0",
+ "--port",
+ "9191",
+ "--path",
+ "/mcp",
+ ],
+ )
+
+ assert result.exit_code == 0
+ fake_server.run_stdio.assert_not_awaited()
+ fake_server.run_streamable_http.assert_awaited_once_with(
+ host="0.0.0.0",
+ port=9191,
+ path="/mcp",
+ debug=False,
+ )
+ fake_server.cleanup.assert_awaited_once()
+
@pytest.mark.skipif(not MCP_AVAILABLE, reason="MCP SDK not installed")
class TestMCPServerInitialization:
diff --git a/uv.lock b/uv.lock
index ffe65b5bf..2693107ef 100644
--- a/uv.lock
+++ b/uv.lock
@@ -1647,6 +1647,8 @@ langchain = [
mcp = [
{ name = "httpx" },
{ name = "mcp" },
+ { name = "starlette" },
+ { name = "uvicorn" },
]
memory = [
{ name = "sentence-transformers", marker = "platform_machine != 'x86_64' or sys_platform != 'darwin'" },
@@ -1844,6 +1846,7 @@ requires-dist = [
{ name = "sqlite-vec", marker = "extra == 'dev'", specifier = ">=0.1.6" },
{ name = "sqlite-vec", marker = "extra == 'memory'", specifier = ">=0.1.6" },
{ name = "sqlite-vec", marker = "extra == 'proxy'", specifier = ">=0.1.6" },
+ { name = "starlette", marker = "extra == 'mcp'", specifier = ">=0.27.0" },
{ name = "strands-agents", marker = "extra == 'strands'", specifier = ">=0.1.0" },
{ name = "tiktoken", specifier = ">=0.5.0" },
{ name = "tomli", marker = "python_full_version < '3.11'", specifier = ">=2.0.0" },
@@ -1857,6 +1860,7 @@ requires-dist = [
{ name = "tree-sitter", marker = "extra == 'code'", specifier = ">=0.25.2,<0.27" },
{ name = "tree-sitter-language-pack", marker = "extra == 'code'", specifier = ">=0.10.0,<1.0" },
{ name = "uvicorn", marker = "extra == 'dev'", specifier = ">=0.23.0,<1.0" },
+ { name = "uvicorn", marker = "extra == 'mcp'", specifier = ">=0.23.0,<1.0" },
{ name = "uvicorn", marker = "extra == 'proxy'", specifier = ">=0.23.0,<1.0" },
{ name = "watchdog", marker = "extra == 'proxy'", specifier = ">=4.0.0" },
{ name = "websockets", marker = "extra == 'dev'", specifier = ">=13.0" },