如何部署BioMCP远程MCP服务器:多个Agent Worker共享一个Streamable HTTP端点的完整指南

原创2026-11-04 14:02:351,861 阅读

如何部署BioMCP远程MCP服务器:多个Agent Worker共享一个Streamable HTTP端点的完整指南

BioMCP 是一个面向生物医学场景的 MCP(Model Context Protocol)服务器:一条命令即可查询 PubMed、ClinVar、ClinicalTrials.gov、OncoKB 等 72 个权威数据源。本文介绍如何用一条 biomcp serve-http 命令,把它部署成远程 MCP 服务器,让多个 Agent Worker 共享同一个 Streamable HTTP 端点 /mcp——你只需维护一份缓存和一组 API Key,所有客户端都能复用。

为什么需要远程 MCP 服务器?

默认情况下,BioMCP 以 stdio 模式运行(biomcp serve),由本地客户端(如 Claude Desktop、Cursor)在进程内拉起。这种模式适合单机,但当你有 多个 Agent Worker 并发工作时,会遇到这些问题:

  • 每个 Worker 各自启动一份 biomcp serve 进程,内存与本地缓存相互独立,无法复用;
  • Worker 运行在容器或远程机器上,根本无法"拉起本地二进制";
  • 上游 API Key(如 NCBI_API_KEY、ONCOKB_TOKEN)分散在各处,配额难以统一管理。

biomcp serve-http 就是为这种 多客户端、容器化、网络化部署 场景设计的:一个进程监听一个端口,所有 Agent Worker 通过 Streamable HTTP 协议访问同一个 /mcp 端点。

BioMCP远程MCP服务器支持多个AI Agent Worker共享同一个Streamable HTTP端点

快速上手:一条命令启动服务器

安装后即可启动(安装方式见 docs/getting-started/installation.md):

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

注意两点硬性约束:

  • 端口必须显式指定(1–65535);端口 0 会被拒绝,因为操作系统随机分配的端口无法让客户端得到可用地址;
  • 本机自测用 127.0.0.1 即可,--host 0.0.0.0 只在需要跨机器/跨容器访问时使用。

启动后,服务端会提供以下路由(详见 docs/getting-started/remote-http.md):

路由 用途
POST /mcp Streamable HTTP MCP 请求入口
GET /mcp Streamable HTTP 会话流
GET /health 存活检查,返回 {"status":"ok"}
GET /readyz 就绪检查,返回 {"status":"ok"}
GET / 身份信息(名称、版本、git 修订、传输方式等)

负载均衡器、Kubernetes 探针或运维脚本可以直接用 /health 和 /readyz 探活。

公开部署必做:用 --allowed-hosts 收紧 Host 白名单

一旦使用 --host 0.0.0.0,BioMCP 会在开启监听器之前强制要求你声明允许接收的 Host 值:

biomcp serve-http --host 0.0.0.0 --port 8080 \
  --allowed-hosts biomcp.example.org,localhost:8080

规则要点:

  • 每条白名单是精确的主机名或 IP,可带端口;IPv6 带端口要写成 [::1]:8080;
  • 不接受协议、路径、通配符和条目内部空格,非法条目会在启动时直接报错;
  • 如果反代会改写 Host 头,白名单里要填 BioMCP 实际收到的值——它不信任 X-Forwarded-Host 等转发头。

这个 Host 白名单防的是 DNS rebinding 类问题,但 它不是认证机制,这一点下面专门说明。

认证模型:把 BioMCP 放在你自己的网关后面

这是远程部署最关键的一条:HTTP 传输本身是无认证的。BioMCP 不内置用户登录、Bearer Token 校验、OAuth 或按用户授权(来源:docs/reference/faq.md 的 FAQ 条目)。

推荐的部署形态是:

Agent Workers ──► 反向代理 / API 网关(TLS + SSO/mTLS/VPN)──► biomcp serve-http
  • 用受信任的反向代理、API 网关、私有网络或 VPN 承担 TLS 与认证;
  • 尽可能让 BioMCP 绑定内网接口,只把认证后的网关暴露给使用者;
  • 上游数据源的 Key 通过环境变量注入到 BioMCP 进程(如 NCBI_API_KEY、ONCOKB_TOKEN、S2_API_KEY),只需在这一个服务上配置一次,所有 Worker 共享配额。完整清单见 docs/getting-started/api-keys.md。

用 Docker 容器化运行

仓库提供了现成的 Dockerfile,官方镜像以非 root 用户(UID 65532)运行,并预置了缓存目录:

docker run --rm -p 8080:8080 -e NCBI_API_KEY=... \
  ghcr.io/genomoncology/biomcp \
  serve-http --host 0.0.0.0 --port 8080 --allowed-hosts biomcp.example.org

容器内缓存与配置都落在 /home/biomcp 下,给该目录挂一个 volume 即可让缓存跨容器重启保留——这对多 Worker 共享场景尤其重要,能显著减少重复的上游请求。

让 Agent Worker 连上来

任何支持 Streamable HTTP 的 MCP 客户端,只需要一个完整 URL:http://<host>:8080/mcp(有网关时换成 https://biomcp.example.org/mcp)。

Python 侧最小连接示例(mcp 官方 SDK):

async with streamable_http_client("http://127.0.0.1:8080/mcp", terminate_on_close=False) as (r, w, _):
    async with ClientSession(r, w) as session:
        await session.initialize()
        result = await session.call_tool("biomcp", arguments={"command": "biomcp get gene BRAF pathways"})

仓库自带一个可直接运行的 demo 客户端,它连接 /mcp 后执行一条三步 BRAF V600E 黑色素瘤工作流(统一搜索 → ClinVar 变异详情 → 临床试验检索),非常适合用来验证多 Worker 接入前的链路连通性:

biomcp serve-http --host 127.0.0.1 --port 8080   # 终端 1
uv run --quiet --script examples/streamable-http/streamable_http_client.py   # 终端 2

BioMCP远程端点可查询的PubMed文章检索与AI摘要等生物医学MCP工具

共享端点上,Worker 能调用的仍是同一套只读工具目录:search、get、variant_normalize_car、variant_erepo、gene_cspec、variant_articles 六个类型化工具,外加原始 biomcp 工具作为逃生舱。所有工具均标注 readOnlyHint: true,写操作类命令(如 skill install、cache clear)在 MCP 模式下会被拒绝;需要结构化结果时传 json: true 即可拿到完整 JSON 契约。工具与资源全貌见 docs/reference/mcp-server.md。

部署核对清单

  • [ ] 端口显式指定,生产环境经网关暴露 TLS;
  • [ ] 非回环绑定已配置 --allowed-hosts,且包含代理实际转发的 Host 值;
  • [ ] 认证/TLS 由网关、SSO/mTLS 或私有网络承担,BioMCP 绑定内网接口;
  • [ ] 上游 API Key 以环境变量注入,单一配置服务所有 Worker;
  • [ ] 用 /health、/readyz 接入探针;缓存目录挂 volume 实现跨重启复用。

小结

biomcp serve 与 biomcp serve-http 暴露的是同一套只读生物医学工具,区别只在传输层:本地单机用 stdio,多 Agent Worker、容器或跨网络部署用 Streamable HTTP。一个端点、一份缓存、一组 API Key,就是 BioMCP 远程 MCP 服务器的全部形态。更多细节可参考 RUN.md 运维手册与 docs/getting-started/remote-http.md。

登录后查看全文
biomcp