驰陌 MCP 接入

在支持 MCP 的客户端里直接接入驰陌，让客户端自带的智能体读取你的运动与健康数据

这是什么

MCP（Model Context Protocol）是让智能体客户端「发现并调用外部工具」的一套标准。驰陌提供官方 MCP 服务：客户端接上之后，你可以直接问「我昨天睡得怎么样」「这周比上周跑得多吗」，由客户端把你的问题翻译成对驰陌数据工具的调用。

它与 REST API 是同一套授权与权限 —— 同一个密钥、同一份数据、同样的限流。区别只在调用方式：REST 需要你自己写请求，MCP 由客户端自动发现有哪些工具可用。

典型用法：把驰陌接进你日常使用的对话式客户端，让它每天早晨读一次你的睡眠与恢复状态，生成当天的训练建议。

一、前置：先拿到密钥

打开驰陌 App →「我的」→「帮助」菜单组 →「智能体接入」。
该功能默认关闭，需要你主动开启并确认授权说明。
生成密钥并复制保存 —— 密钥只在生成时展示一次，之后无法再次查看。
密钥永久有效，可随时重置或关闭接入；重置后旧密钥立即失效。

二、服务地址

把下面这个地址填进 MCP 客户端的「远程 / HTTP」服务地址（Streamable HTTP）：

https://api.8keya.com/mcp

该服务无状态：服务端不保存、不缓存你的数据，也不持有长期密钥 —— 每次请求都用你随请求带来的密钥鉴权。响应为普通 JSON（非 SSE 长连接）。

三、认证

MCP 客户端通过请求头携带密钥（没有单独的登录流程）：

X-API-Key: sk_sm_...xxxx

密钥等同于你的数据读取权限。请勿写入代码仓库、截图或分享给他人；若怀疑泄露，请立即在 App 内重置。

四、客户端配置

任何支持自定义请求头的 MCP 客户端都可以接入。以 OpenClaw 为例（已实测可用）：

openclaw mcp add stridemoor \
     --url https://api.8keya.com/mcp \
     --transport streamable-http \
     --header X-API-Key=sk_sm_...xxxx

命令行式客户端（如 Claude Code）同样支持自定义请求头，具体参数见其自带帮助。

Claude 桌面版 / 网页版 / 手机版目前接不进来：这类客户端的连接由 Anthropic 云端发起，配置界面只接受 URL 与 OAuth 凭据，没有自定义请求头这一项，因此无法携带 X-API-Key。它们需要的是 OAuth —— 驰陌暂未提供。

五、可用工具

接上以后客户端会自动列出可用工具。只读工具（共 11 个）只要密钥有效就全部可用：

工具	说明
get_capabilities	查看这枚密钥能做什么：权限范围、限流额度、可用端点
get_overview	今日全貌：步数 / 距离 / 热量、最近一次跑步、恢复状态
get_today	指定某天的全部身体指标（步数 / 睡眠 / 最大摄氧量 …），数值都带单位
get_weekly_report	本周与上周的跑量、时长、次数、配速对比
get_recent_runs	最近若干次跑步的摘要
get_health_summary	近 N 天健康汇总：步数 / 距离 / 热量 / 睡眠 / 最大摄氧量 / 心电图条数；只给汇总不给原始时序点，不含心率 / 血氧 / 体温（那三类走 REST /health/data-points）
list_runs	分页列出跑步记录
get_run_detail	按 ID 查单次跑步详情（配速、心率、步频 …）
list_bookmarks	本人收藏的跑步记录
list_routes	分页列出路线
list_favorite_routes	本人收藏的路线

写工具（默认不可用）

下列 8 个工具只在密钥带对应写权限时才会出现在工具列表里 —— 这样模型看到的能力与密钥真实能力一致，不会去调一个必然被拒的工具。写权限默认不授予，需要你在 App「智能体接入」里显式勾选「同时授予写入权限」。写操作只影响你自己的数据（收藏、关注），不能新增、修改或删除你的跑步记录、健康数据、积分与账号信息。

工具	需要权限	说明
bookmark_run	write:bookmarks	收藏一次跑步记录
unbookmark_run	write:bookmarks	取消收藏一次跑步记录
favorite_run	write:favorites	把一次跑步记录加入收藏
unfavorite_run	write:favorites	把一次跑步记录移出收藏
favorite_route	write:favorites	收藏一条路线
unfavorite_route	write:favorites	取消收藏一条路线
follow_user	write:follow	关注一个用户（不能关注自己）
unfollow_user	write:follow	取消关注一个用户

六、限流

与 REST API 一致：默认每把密钥每分钟 60 次、每天 5000 次。超限返回 429。

七、常见问题

连上后只看到只读工具，我在 App 里开的写权限没生效？
不是没生效。远端服务是无状态的，第一次请求时还来不及读取你密钥的权限范围，会先只注册只读工具（约 2~3 秒后自动补齐写工具并通知客户端刷新列表）。隔几秒重连一次、或让客户端刷新一次工具列表，就能看到全部工具。写工具是否出现，只取决于密钥是否带对应写权限。

自己写客户端（Python 等）调用时返回 403？
我们的入口前面有 Cloudflare，会拦截默认的 Python 客户端标识（HTTP 403，Error 1010）。给请求带上常规的 User-Agent（如 curl/8.0 或你自己的客户端名）即可。使用官方 MCP SDK 的客户端不受影响。

客户端连不上、或提示初始化超时？
请把连接/初始化超时放宽到 30 秒以上：入口经 Cloudflare 转发，单次请求有 1~2 秒的固定时延，默认 5 秒的超时可能不够。

八、隐私与免责

数据由驰陌服务器直接返回给你指定的调用方，驰陌不会把数据另外提供给第三方。
健康类数据来自消费级穿戴设备，仅供参考，不构成医疗建议，不得用于诊断或治疗决策。
你可以随时在 App 内关闭接入或重置密钥，重置后原密钥立即失效。