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.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
feat(mcp): add streamable HTTP MCP transport (#1773)
Rod Boev4ea96a417cee
diff --git a/docs/content/docs/mcp.mdx b/docs/content/docs/mcp.mdxindex bd6978fd2..af6302825 100644--- a/docs/content/docs/mcp.mdx+++ b/docs/content/docs/mcp.mdx@@ -115,6 +115,9 @@ headroom mcp uninstall# Debug modeheadroom 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 startdiff --git a/headroom/ccr/mcp_http.py b/headroom/ccr/mcp_http.pynew file mode 100644index 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.pyindex 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.pyindex bcef72e51..a9ea4228e 100644--- a/headroom/cli/mcp.py+++ b/headroom/cli/mcp.py@@ -17,6 +17,9 @@ from .main import mainCLAUDE_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).\bThis 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.\bFor manual testing:headroom mcp serve --debug+ headroom mcp serve --transport http --host 127.0.0.1 --port 8788 --path /mcp"""import asyncioimport 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 specifiedeffective_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.tomlindex 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 detectionvoice = [diff --git a/tests/test_ccr_mcp_http.py b/tests/test_ccr_mcp_http.pynew file mode 100644index 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_namesdiff --git a/tests/test_cli/test_mcp.py b/tests/test_cli/test_mcp.pyindex 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 jsonimport sys-from unittest.mock import MagicMock, patch+from unittest.mock import AsyncMock, MagicMock, patchimport pytestfrom 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.outputassert "proxy-url" in result.outputassert "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.lockindex 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" },