如何部署BioMCP远程MCP服务器:多个Agent Worker共享一个Streamable HTTP端点的完整指南
如何部署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 端点。
快速上手:一条命令启动服务器
安装后即可启动(安装方式见 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
共享端点上,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。

