Skip to content

Remote Streamable HTTP Server

Use biomcp serve-http when you need one shared MCP server for remote clients, multiple agent workers, or a container/network deployment.

Use biomcp serve when a single local client such as Claude Desktop or Cursor launches BioMCP over stdio.

Start the server

biomcp serve-http --host 127.0.0.1 --port 8080

Use --host 0.0.0.0 only when the server must accept connections from other machines or containers.

MCP endpoint and probes

The canonical MCP endpoint is /mcp. Probe routes are /health, /readyz, and /.

Route Purpose
POST /mcp Streamable HTTP MCP requests
GET /mcp Streamable HTTP session stream
GET /health Liveness check returning {"status":"ok"}
GET /readyz Readiness check returning {"status":"ok"}
GET / BioMCP identity document with name, version, transport, and MCP path

Minimal Python client

import asyncio
from datetime import timedelta

from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client


async def main() -> None:
    async with streamable_http_client(
        "http://127.0.0.1:8080/mcp",
        terminate_on_close=False,
    ) as (r, w, _):
        async with ClientSession(
            r,
            w,
            read_timeout_seconds=timedelta(seconds=30),
        ) as session:
            result = await session.initialize()
            print(result.serverInfo)


asyncio.run(main())

Runnable demo

The repo includes a standalone demo you can run directly. It keeps the Streamable HTTP connectivity proof, then runs a three-step BRAF V600E melanoma workflow over the remote MCP biomcp tool:

  • biomcp search all --gene BRAF --disease melanoma --counts-only
  • biomcp get variant "BRAF V600E" clinvar
  • biomcp search trial -c melanoma --mutation "BRAF V600E" --limit 5
biomcp serve-http --host 127.0.0.1 --port 8080
uv run --script examples/streamable-http/streamable_http_client.py
uv run --script examples/streamable-http/streamable_http_client.py http://127.0.0.1:8080

The demo connects to /mcp, prints Command: ... before each BioMCP step, and leaves the real markdown output untouched so a screenshot or recording still makes sense without extra narration.

See examples/streamable-http/README.md for the short newcomer walkthrough, expected output markers, uv run --quiet guidance for first-run dependency noise, and the release-binary note for repo verification.

The examples above disable explicit session termination because the current Python MCP client logs a warning when the server acknowledges teardown with HTTP 202 Accepted (terminate_on_close=False in the demo client).