MCP 接入

通过 /mcp，可以让 Claude Code、Codex、Cursor 等客户端查询你的健康记录。如果只需离线查编码和单位，不涉及个人记录，请使用下文的 stdio 服务。查询结果的去向由客户端决定：即使 Mirobody 使用本地模型，云端助手仍会收到它查询的读数。要让整个过程留在本机，客户端也需要使用本地模型。

端点

路由	识别调用者的方式	用途
`POST /mcp`	`Authorization: Bearer <access token>`	能发送请求头的客户端
`POST /mcp/<secret>`	路径中的 secret	个人 URL，供无法发送请求头的客户端使用
`GET /personal/mcp`	`Authorization: Bearer <access token>`	列出调用者创建的链接，以及别人创建的、能读取调用者本人记录的链接
`POST /personal/mcp`	`Authorization: Bearer <access token>`	替换调用者的个人 URL（body 中带 `user_id` 时，替换的是某位家庭成员指向该人的链接）
`DELETE /personal/mcp`	`Authorization: Bearer <access token>`	吊销调用者为该人创建的链接（自己的，或请求体带 `user_id` 时为家庭成员创建的那条）
`DELETE /personal/mcp/<id>`	`Authorization: Bearer <access token>`	按 id 吊销一条链接，无论它是调用者创建的还是读取调用者本人记录的

设置了 HTTP_URI_PREFIX 时，以上路由都位于该前缀之下。在 Docker 栈上，服务端监听端口。

个人 MCP URL

在 Web 客户端的设置 → MCP 链接中生成个人链接，再将链接填入外部客户端。个人链接已包含访问凭据，客户端无需另行登录。也可以通过 API 生成：

# 用演示账号登录（真实部署按其用户的方式登录）
TOKEN=$(curl -s -X POST http://localhost:18060/email/verify \
  -H 'Content-Type: application/json' \
  -d '{"email": "you@mirobody.ai", "code": "111111"}' | jq -r .data.access_token)

curl -s -X POST http://localhost:18060/personal/mcp -H "Authorization: Bearer $TOKEN"

{ "code": 0, "msg": "ok", "data": { "url": "http://localhost:18060/mcp/<secret>" } }

一条链接只读一个人的记录。设置 → MCP 链接里，你自己的记录一行，每位允许你查看记录的家人各一行。要在 MCP 客户端里查家人的记录，就在对方那一行生成链接，作为另一个服务器添加。通过 API 生成时，在 POST /personal/mcp 的请求体里传入对方的 user_id。为同一份记录重新生成链接后，原链接立即失效。链接有效期由 MCP_URL_TTL_DAYS 设置，默认天，使用过程中不会自动续期。可在设置页或通过上方接口查看、撤销链接。共享权限或创建者授权失效后，链接也会失效。之后重新共享记录，不会恢复已经撤销的旧链接。

请像保护密码一样保护个人链接：任何持有者都能读取对应记录。不要公开配置文件或包含链接的截图；设备丢失时及时撤销链接，开放网络访问时使用 HTTPS。

URL 的开头是请求到达时使用的源。位于反向代理之后时，只有服务端信任代理转发的请求头，这个源才正确，见在服务器上部署。

账号能看到的工具

端点提供以下工具： tools/list 按账号过滤：账号中没有某类数据时，对应的数据工具会被隐藏，客户端因此不会看到一个只能回答“没有数据”的工具。参与过滤的是。每个工具接受什么参数、返回什么，见健康数据工具；你自己添加的工具也以同样方式提供，见添加工具。仅用于对话的工具（文件工具、code_exec 与 ask_user）不通过 MCP 提供。

连接客户端

把下文中的 URL 换成你的个人 URL。

Cursor
Claude Code
Codex
Gemini CLI
Claude Desktop

Cursor 可以直接连接远程服务。在 ~/.cursor/mcp.json 或项目中的 .cursor/mcp.json 里添加：

{
  "mcpServers": {
    "mirobody": { "url": "http://localhost:18060/mcp/<secret>" }
  }
}

claude mcp add --transport http mirobody http://localhost:18060/mcp/<secret>

codex mcp add mirobody --url http://localhost:18060/mcp/<secret>

gemini mcp add --transport http mirobody http://localhost:18060/mcp/<secret>

Claude Desktop 以自定义连接器的方式添加远程服务，需要一个它能访问到的 HTTPS 地址。对于运行在你自己机器上的引擎，请改为在 claude_desktop_config.json 中通过 stdio 桥接：

{
  "mcpServers": {
    "mirobody": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:18060/mcp/<secret>"]
    }
  }
}

ChatGPT 和 claude.ai 同样从云端连接，所以需要一个它们能访问到的 HTTPS 地址：请先把整套服务部署到服务器上。你自己的 agent 循环可以用任意 MCP 客户端库调用该端点。服务端使用当前的无状态协议版本，并能为仍使用 initialize 握手的客户端协商降级。

通过 stdio 使用本地术语工具

如果只需术语查询，无须运行服务端或创建个人记录。运行 uvx --python 3.12 mirobody mcp，即可从已发布的软件包启动 stdio MCP 服务；--python 3.12 让 uv 自行获取软件包需要的解释器，否则较旧的默认解释器会选到 1.2 之前的版本。如果已经安装 Mirobody，也可以运行 mirobody mcp。读数、主诉、指标及单位的标准化无须数据库或模型密钥。在支持启动本地 MCP 进程的客户端中，使用以下配置：

{
  "mcpServers": {
    "mirobody": {
      "command": "uvx",
      "args": ["--python", "3.12", "mirobody", "mcp"]
    }
  }
}

该服务提供 standardize_reading，将读数转为带 LOINC 和 UCUM 编码的 FHIR Observation；standardize_complaint 对主诉做 ICPC-3 编码；resolve_indicator、normalize_unit 和 convert_unit 用于术语查询。standardize_report 可以读取 PDF、图片、表格或文本报告；该工具还需要 mirobody[parse] 扩展与模型密钥，文档内容会发送给选定的模型服务商。使用 uvx 时，可以运行 uvx --python 3.12 --from 'mirobody[parse]' mirobody mcp 来启用这个工具。需要访问个人健康记录时，请使用上文的个人 URL。协议实现与按账号过滤的逻辑位于。

开始使用

模型

架构

① 收集

② 标准化

③ 智能体

扩展

部署

端点

个人 MCP URL

账号能看到的工具

连接客户端

通过 stdio 使用本地术语工具

​端点

​个人 MCP URL

​账号能看到的工具

​连接客户端

​通过 stdio 使用本地术语工具

端点

个人 MCP URL

账号能看到的工具

连接客户端

通过 stdio 使用本地术语工具