MCP: optional streamable-HTTP transport for remote / shared deployments

[DvirDukhan]

Context

cgraph-mcp currently runs stdio only (app.run(transport="stdio") in api/mcp/server.py). This matches how local agents (Claude Code, Cursor) consume MCP today — one short-lived stdio session per call — but it precludes:

• Sharing a single MCP server across multiple agents on a host (each call respawns the binary; pays ~0.5–1 s spawn + initialize per tool call)
• Remote / containerized deployments where the server runs once and clients connect over the network
• Benchmarking a 'persistent server' cost basis distinct from the per-call-spawn cost

Proposal

Add an opt-in streamable-http transport. FastMCP already supports it natively; the change is small:

def main() -> None:
    import argparse
    p = argparse.ArgumentParser()
    p.add_argument("--transport", choices=["stdio", "http"], default="stdio")
    p.add_argument("--host", default="127.0.0.1")
    p.add_argument("--port", type=int, default=8765)
    p.add_argument("--path", default="/mcp")
    args = p.parse_args()
    ensure_falkordb(); maybe_auto_index()
    if args.transport == "http":
        app.run(transport="streamable-http", host=args.host, port=args.port, path=args.path)
    else:
        app.run(transport="stdio")

Default stays stdio so no existing client breaks.

Why streamable-http and not SSE

The MCP spec (2025-03) deprecates the SSE transport in favor of streamable-http. New work should target streamable-http; SSE only as legacy.

Acceptance criteria

• cgraph-mcp --transport http --port 8765 starts a server reachable at POST http://127.0.0.1:8765/mcp speaking JSON-RPC.
• All 8 existing tools (index_repo, search_code, get_callers, get_callees, get_dependencies, impact_analysis, find_path, ask) reachable over the new transport with identical schemas.
• Default invocation (cgraph-mcp) remains stdio — no behavior change for current callers.
• One integration test that hits the HTTP endpoint via mcp.client.streamable_http.streamablehttp_client and exercises search_code.
• Doc / README snippet showing how to run the HTTP server and connect a client.

Out of scope

• Authentication / authz on the HTTP endpoint (file a follow-up if needed)
• SSE legacy support
• Optimizing the bench harness to keep a persistent connection (separate ticket; this issue only opens the door)

References

• MCP spec, Streamable HTTP transport: https://spec.modelcontextprotocol.io/specification/2025-03-26/basic/transports/#streamable-http
• FastMCP transport docs (https://github.com/modelcontextprotocol/python-sdk)