Zoom Whiteboard MCP 接入实战指南:认证路径、必需 Scopes 与 Whiteboard ID 映射
Zoom Whiteboard MCP 接入实战指南:认证路径、必需 Scopes 与 Whiteboard ID 映射
本文基于 knowledge-work-plugins 仓库中
partner-built/zoom-plugin/skills/zoom-mcp/whiteboard/SKILL.md技能文档展开,系统讲解 Zoom Whiteboard MCP 服务器的端点、User OAuth 与 S2S OAuth 两种认证路径的选择、读写 Scopes、whiteboard_id的 URL 映射规则、8 个可用工具以及从list_whiteboards到get_a_whiteboard的读取工作流。读完本文,你将能独立完成 Whiteboard MCP 的令牌注入、工具发现、白板 ID 确认与内容读取,并能在遇到 scope 报错、工具找不到等问题时快速定位根因。
一、Whiteboard MCP:独立于 Zoom MCP 的白板工具面
在 knowledge-work-plugins 仓库中,Zoom 相关的 MCP 连接能力被拆分为多个独立的工具面。白板(Whiteboard)专用 MCP 服务器与主 Zoom MCP 服务器是两个不同的端点,请求路由时需要区分对待:
- 会议语义搜索、会议资产、录制资源等请求走主 Zoom MCP(
zoom-mcp); - Zoom Docs 走专用的
zoom-docs-mcp; - 白板相关请求则应路由到
zoom-mcp/whiteboard这一专用技能。
这一结论在 父级技能文档 中被明确标注:"Whiteboard is a separate MCP surface. The Zoom MCP endpoint and the Whiteboard MCP endpoint are separate. Route Whiteboard-specific requests to whiteboard/SKILL.md." 同时在 MCP 架构文档 的 "Hosted Zoom MCP Surfaces" 一节中,Whiteboard MCP 与 Zoom MCP 被并列列出,共享同一套 MCP 协议发现模型。
仓库中 partner-built/zoom-plugin/.mcp.json 也印证了这一点——它同时声明了三个独立的 MCP 服务器,其中 Whiteboard 服务器是单独定义的:
{
"mcpServers": {
"zoom-mcp": {
"type": "http",
"url": "https://mcp-us.zoom.us/mcp/zoom/streamable",
"headers": {
"Authorization": "Bearer ${ZOOM_MCP_ACCESS_TOKEN}"
}
},
"zoom-docs-mcp": {
"type": "http",
"url": "https://mcp.zoom.us/mcp/docs/streamable",
"headers": {
"Authorization": "Bearer ${ZOOM_DOCS_MCP_ACCESS_TOKEN}"
}
},
"zoom-whiteboard-mcp": {
"type": "http",
"url": "https://mcp-us.zoom.us/mcp/whiteboard/streamable",
"headers": {
"Authorization": "Bearer ${ZOOM_WHITEBOARD_MCP_ACCESS_TOKEN}"
}
}
}
}
可以看到,Whiteboard 连接器通过 ZOOM_WHITEBOARD_MCP_ACCESS_TOKEN 环境变量注入 Bearer 令牌,且指向独立的 https://mcp-us.zoom.us/mcp/whiteboard/streamable 端点。这意味着它拥有独立的令牌变量、独立的端点、独立的 scope 集合,不能与 Zoom MCP 的令牌混用。
二、端点(Endpoints):Streamable HTTP 为主,SSE 兜底
Whiteboard MCP 服务器提供两种传输方式,与仓库 技能文档 中记录的端点一致:
| Transport | URL |
|---|---|
| Streamable HTTP(推荐) | https://mcp-us.zoom.us/mcp/whiteboard/streamable |
| SSE(兜底) | https://mcp-us.zoom.us/mcp/whiteboard/sse |
从 .mcp.json 的连接器配置看,bundled connector 实际使用的是 Streamable HTTP 形态,通过 HTTP Authorization: Bearer ${ZOOM_WHITEBOARD_MCP_ACCESS_TOKEN} 请求头携带令牌。SSE 端点作为 fallback 存在,适合那些不支持 Streamable HTTP 但支持 SSE 的 MCP 客户端。
参考文档 认证与标识符 同样以这两个 URL 作为其指导对象的锚点,说明两类传输共享同一认证模型与 scope 要求。
三、认证(Authentication):User OAuth 是已验证路径
3.1 User OAuth:首选且已验证
Whiteboard MCP 的认证核心结论是:User OAuth(用户级 OAuth)配 Whiteboard scopes 是已验证可用的路径,至少对 list_whiteboards 和 get_a_whiteboard 两个读取工具成立。这也是 认证与标识符参考文档 记录的实测结论。
用户级 OAuth 的完整流程可参考 OAuth 设置指南,要点包括:
- 在 Zoom Marketplace 创建 General app,配置为 user-level OAuth;
- 设置回调地址(开发期可先用
localhost手动复制授权码,或用ngrok暴露本地回调服务); - 在应用中勾选 Whiteboard MCP 所需的粒度 scopes(见下文第四节);
- 构造授权 URL
https://zoom.us/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI,完成用户授权; - 用授权码换取令牌:
curl -X POST https://zoom.us/oauth/token \ -u "CLIENT_ID:CLIENT_SECRET" \ -d "grant_type=authorization_code&code=CODE&redirect_uri=REDIRECT_URI" - 将返回的
access_token注入环境变量ZOOM_WHITEBOARD_MCP_ACCESS_TOKEN,重启 Claude Code 或重新启用插件,使 bundled MCP 服务器以新令牌重启。
关于令牌生命周期,参考 OAuth 设置指南 的说明:access token 有效期约为 1 小时,之后需要用 refresh_token 换取新的 access token 与新的 refresh token,且refresh token 是单次使用的——每次刷新都会返回新的 refresh token,必须原子化地同时持久化新旧令牌,并在刷新成功后废弃旧 refresh token,避免并发刷新。
3.2 S2S OAuth:只能到达网关,工具执行需单独验证
Server-to-Server(S2S)OAuth 的情况要复杂得多。据 认证与标识符参考文档 的记录:
- S2S OAuth 可以到达 Whiteboard MCP 网关,并能完成协议发现(
tools/list); - 但白板读取工具的执行必须针对你的应用和 Whiteboard scopes 单独验证;
- 实测中出现过一种典型的运行时错误形态:
Invalid access token, does not contain scopes:[whiteboard:read:admin,whiteboard:read]
这条错误信息表明:S2S 应用令牌虽然能连上网关,但缺少网关预期的 scopes,导致工具执行被拒绝。因此技能文档给出了务实的操作原则:Whiteboard MCP 优先使用 User OAuth,除非你已经证明自己的 S2S 应用能够铸造并执行带有所需 Whiteboard scopes 的令牌。
这一建议与 父级技能文档 中 "User OAuth is the documented execution path" 的总原则一致,也与 RUNBOOK 中的 "Auth Reality Check" 相呼应:不要依赖 S2S OAuth 作为该插件中受支持的 MCP 认证模型。
3.3 令牌注入:bundled connector 的环境变量约定
Whiteboard MCP 令牌必须通过 ZOOM_WHITEBOARD_MCP_ACCESS_TOKEN 环境变量注入,这是 .mcp.json 中 zoom-whiteboard-mcp 服务器的固定约定(Authorization: Bearer ${ZOOM_WHITEBOARD_MCP_ACCESS_TOKEN})。注意它与主 Zoom MCP 的 ZOOM_MCP_ACCESS_TOKEN、Docs MCP 的 ZOOM_DOCS_MCP_ACCESS_TOKEN 是三个不同的变量,不可互相替代。
验证令牌是否生效的快速检查:
echo "${ZOOM_WHITEBOARD_MCP_ACCESS_TOKEN:+set}"
输出 set 表示变量已注入;随后重启 Claude Code 或重新启用插件,再通过 tools/list 确认 Whiteboard 工具已出现在客户端。
四、必需 Scopes:Whiteboard 的粒度权限集合
Whiteboard MCP 使用 MCP 专属的粒度 scopes(与旧版宽泛 REST scopes 不同)。据 技能文档、认证与标识符参考文档 和 工具参考文档 的一致记录,Whiteboard MCP 通过 OAuth protected-resource metadata 公布的 scopes 如下:
| Scope | 类型 | 用途 |
|---|---|---|
whiteboard:read:list_whiteboards |
读 | 列出当前用户/管理员上下文可访问的白板(对应 list_whiteboards) |
whiteboard:read:whiteboard |
读 | 按 whiteboard_id 读取白板内容(对应 get_a_whiteboard) |
whiteboard:write:whiteboard |
写 | 更新白板元数据等写操作(网关公布但需验证) |
实操建议:
- 只做读取(
list_whiteboards、get_a_whiteboard)时,User OAuth 令牌至少需要前两个读 scope; - 若要使用
update_a_whiteboard_metadata等写工具,则需要whiteboard:write:whiteboard; - 参考 MCP 架构文档 的说明:这些 scope 属于 "Protected Resource Metadata",由托管 MCP 表面通过 OAuth 元数据公布;务必以服务端实际公布的 scope 集合为准,而不是假设。
从错误形态也可以反向确认 scope 的作用:当令牌缺少所需 scope 时,服务端会返回 Invalid access token, does not contain scopes:<a href="https://link.gitcode.com/i/0780e340576477f3faef2752728eae10" target="_blank">...] 形式的错误,其中方括号内即缺失的 scope 列表。排障时对比该列表与上述三枚 scope 即可定位问题(详见 [常见错误排障 中的 -32001 类条目)。
五、Whiteboard ID 映射:取 /wb/db/ 后的段,而非 /p/ 后的数字
这是 Whiteboard MCP 最容易踩坑的地方。Zoom 白板的分享/访问 URL 形如:
https://us05whiteboard.zoom.us/wb/db/6iktP8hJT3e5qaCuwFuAGg/p/180968285929472
^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
whiteboard_id page/subresource id
- 正确的 MCP
whiteboard_id:URL 中/wb/db/之后、/p/之前的段,即6iktP8hJT3e5qaCuwFuAGg; - 不是
/p/之后的那串数字(180968285929472),那是页面/子资源标识符,不是 Whiteboard MCP 使用的白板标识。
认证与标识符参考文档 对此有同样的明确记录:"The MCP-facing whiteboard_id matches the URL segment after /wb/db/. The numeric /p/... segment is not the Whiteboard MCP identifier."
为什么这很重要?因为 get_a_whiteboard 依赖 whiteboard_id 定位目标白板,拿错 ID 段将导致无法命中目标。稳妥的做法是:先用 list_whiteboards 发现可访问的白板并确认服务端返回的 whiteboard_id,而不是手工从 URL 猜测。手工从 URL 解析时,务必记住规则:/wb/db/ 之后的第一个路径段才是白板 ID。
六、可用工具目录:8 个 Whiteboard MCP 工具
据 工具参考文档,当前 Whiteboard MCP 在 https://mcp-us.zoom.us/mcp/whiteboard/streamable 上的 tools/list 结果包含 8 个工具:
| 工具 | 用途 | 覆盖情况 |
|---|---|---|
create_a_whiteboard_for_brainstorming |
根据头脑风暴输入(问题、想法、下一步)创建白板 | 已出现在 Whiteboard MCP 表面;使用前需校验请求 schema |
list_whiteboards |
列出当前用户或管理员上下文可访问的白板 | 由本技能读取工作流覆盖 |
create_a_whiteboard |
创建白板 | 已出现在 Whiteboard MCP 表面;使用前需校验请求 schema |
get_a_whiteboard |
按 whiteboard_id 检索白板 |
由本技能读取工作流覆盖 |
create_a_whiteboard_by_script |
通过脚本化内容或结构化输入创建白板 | 已出现在 Whiteboard MCP 表面;使用前需校验请求 schema |
update_a_whiteboard_metadata |
更新白板元数据 | 已出现在 Whiteboard MCP 表面;使用前需校验请求 schema |
create_a_whiteboard_for_meeting_summary |
从会议摘要式输入生成白板 | 已出现在 Whiteboard MCP 表面;使用前需校验请求 schema |
create_a_whiteboard_for_strategy_analysis |
为战略分析内容生成白板 | 已出现在 Whiteboard MCP 表面;使用前需校验请求 schema |
需要特别注意两点:
- 部分 MCP 客户端会在 UI 中为服务器工具加命名空间(例如显示为
zoom-whiteboard-mcp:list_whiteboards)。以技能文档的记录为准:原始工具名(raw tool names)才是权威,加命名空间只是客户端展示层的差异。 - 8 个工具中,读取类工具(
list_whiteboards、get_a_whiteboard)已被本技能完整覆盖并有实测结论;其余创建/更新类工具虽然出现在工具面上,但技能文档建议在使用前通过tools/list校验其实际请求 schema,不要凭工具名臆断参数结构。
关于工具发现的权威机制,参考 MCP 架构文档 的 "Discovery Model":不要在客户端逻辑中硬编码工具数量或工具清单,应以 MCP 协议 tools/list 的实时响应作为工具名、描述、参数 schema 的当前事实来源。这与 Whiteboard 技能"以原始工具名为准"的提示互为印证。
七、读取工作流:三步入手
技能文档给出了最小可用的读取工作流,这是本技能覆盖最完整、验证最充分的路径:
- 准备令牌:使用带 Whiteboard 读 scopes(
whiteboard:read:list_whiteboards、whiteboard:read:whiteboard)的 User OAuth 令牌,注入ZOOM_WHITEBOARD_MCP_ACCESS_TOKEN; - 发现白板:调用
list_whiteboards,列出可访问的白板,并确认正确的whiteboard_id(对照第五节 ID 映射规则); - 读取内容:用上一步得到的
whiteboard_id调用get_a_whiteboard。
这三个步骤对应 技能文档 的 "Read Workflow" 一节,也呼应了父级技能"先发现、后操作"的通用模式(主 Zoom MCP 中同样是先 search_meetings / recordings_list 定位目标,再执行内容检索)。
响应形状(Response Shape)提示
一个重要的实测细节(记录于 认证与标识符参考文档):get_a_whiteboard 返回的载荷是一个列表风格的 payload(其中包含匹配到的白板),而不是显而易见"单个对象"的载荷。
也就是说,不要因为工具名里带 a(单数冠词)就假设响应一定是单对象结构。正确的做法是:以实际服务端返回的响应形状为准来解析——先打印/检查真实返回结构,再编写解析逻辑。这与 MCP 架构文档 中 "When writing parsers, validate the live response shape from the server rather than relying on older example field names" 的建议完全一致。
八、常见错误与排障速查
结合 常见错误排障 与 RUNBOOK,Whiteboard MCP 场景下最常见的失败形态与处置如下:
| 症状 | 可能原因 | 处置 |
|---|---|---|
-32001 Access token is required |
ZOOM_WHITEBOARD_MCP_ACCESS_TOKEN 未设置或为空,未发送 Authorization 头 |
导出令牌并重启 Claude Code / 重新启用插件 |
-32001 Invalid access token, does not contain scopes:[...] |
令牌过期、被吊销,或缺少工具所需的 MCP 粒度 scopes(如 whiteboard:read:whiteboard) |
刷新令牌,核对并补齐 Whiteboard scopes,重新铸造用户令牌 |
-32602 Can not found tool: ... |
请求的工具不在当前 MCP surface 上,或请求发到了错误的 surface | 确认端点地址(Whiteboard 应为 https://mcp-us.zoom.us/mcp/whiteboard/streamable),重新 tools/list 并使用当前工具名 |
| 工具执行返回列表形态而非预期对象 | 服务端实际响应就是列表 payload | 按实际响应形状解析,而非按工具名假设 |
此外,常见错误排障 还记录了 MCP 协议层与底层 Zoom API 风格错误的两层结构(对应 MCP 架构文档 的 "Error Layering"):-32001 / -32602 / -32603 属于 MCP 协议层错误,而 scope 拒绝、资源不存在等则属于底层 Zoom API 风格错误经由 MCP 响应上浮。排查时先分清是哪一层,再对症下药。
九、技能路由与相关文档导航
在 knowledge-work-plugins 仓库中使用 Zoom MCP 时,正确的路由优先级是:
- 一般性 MCP 工作流规划/故障排查,先参考 design-mcp-workflow 与 setup-zoom-mcp;
- 请求明确涉及白板 MCP(认证、端点、ID 映射、
list_whiteboards/get_a_whiteboard等工具工作流)时,优先使用本技能zoom-mcp/whiteboard,而不是泛化的 Zoom MCP 技能; - 主 Zoom MCP(会议搜索、会议资产、录制资源)走 父级技能;
- Zoom Docs 走独立的
zoom-docs-mcp。
本技能的完整参考链如下(均已转换为仓库根目录相对路径):
- whiteboard 技能文档 — 本指南的主体来源,含端点、认证、Scopes、ID 映射、工具与读取工作流;
- 认证与标识符参考文档 — 认证行为实测细节、S2S 错误形态、ID 映射与响应形状提示;
- 工具参考文档 — 8 个工具的目录表与 scope 家族;
- 父级 Zoom MCP 技能 — 主 MCP / Docs MCP / Whiteboard MCP 三面路由总览;
- OAuth 设置指南 — User OAuth 应用创建、scope 配置、令牌交换与生命周期;
- MCP 架构文档 — 托管 MCP surface、发现模型、protected-resource metadata 与错误分层;
- 常见错误排障 — 认证、scope、连接与参数类错误清单;
- RUNBOOK — 5 分钟预检清单与快速修复表;
- 连接器配置 —
zoom-whiteboard-mcp服务器定义与ZOOM_WHITEBOARD_MCP_ACCESS_TOKEN注入约定。
十、要点总结
- Whiteboard MCP 是独立 surface:独立端点(
/mcp/whiteboard/streamable)、独立令牌变量(ZOOM_WHITEBOARD_MCP_ACCESS_TOKEN)、独立 scope 集合,与 Zoom MCP 不可混用; - 认证选 User OAuth:S2S 只能到达网关完成
tools/list,工具执行需单独验证,且实测会暴露does not contain scopes错误; - Scopes 按需申请:读取至少
whiteboard:read:list_whiteboards+whiteboard:read:whiteboard,写操作另需whiteboard:write:whiteboard; - ID 取
/wb/db/后段:不要误用/p/后的数字段; - 工作流先发现后读取:
list_whiteboards确认 ID →get_a_whiteboard读取,且解析时以实际响应形状为准(get_a_whiteboard实测返回列表风格 payload); - 工具名以原始名为准:客户端 UI 可能加命名空间前缀,排障与编程时应使用 raw tool names。