Zoom Whiteboard MCP 认证与标识符映射实战指南knowledge-work-plugins 插件篇【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins本指南以partner-built/zoom-plugin插件仓库中 Whiteboard MCP 专用技能文档为核心系统讲解 Zoom Whiteboard MCP 服务https://mcp-us.zoom.us/mcp/whiteboard/streamable与https://mcp-us.zoom.us/mcp/whiteboard/sse的认证方式、权限范围Scope、白板标识符whiteboard_id映射规则与响应解析要点。读者学完后可以正确区分 User OAuth 与 Server-to-ServerS2SOAuth 在该服务上的能力边界配置出可用的读工具调用链list_whiteboards→get_a_whiteboard并能从白板分享链接中准确提取 MCP 所需的标识符避免因错误 ID 或错误响应假设导致的集成失败。一、服务端点与适用场景Whiteboard MCP 是 Zoom 提供的托管 MCP 服务面之一与主 Zoom MCP 服务、Zoom Docs MCP 服务是相互独立的三个表面。其推荐端点与回退端点如下传输方式URLStreamable HTTP推荐https://mcp-us.zoom.us/mcp/whiteboard/streamableSSE回退https://mcp-us.zoom.us/mcp/whiteboard/sse需要特别强调的是Whiteboard 相关请求不要发往主 Zoom MCP 端点https://mcp-us.zoom.us/mcp/zoom/streamable或 Docs MCP 端点https://mcp.zoom.us/mcp/docs/streamable。在 troubleshooting/common-errors.md 中Can not found tool: ... in this MCP Server-32602的常见成因之一就是请求被发到了错误的 MCP 表面修复方式即确认当前使用的是 Whiteboard MCP 端点。从仓库结构看zoom-mcp/SKILL.md 负责主 Zoom MCP 与 Docs MCP 的路由whiteboard/SKILL.md 则是 Whiteboard MCP 的专用入口其触发词包括whiteboard mcp、list zoom whiteboards、zoom wb/db等。当任务涉及白板认证、端点、ID 映射或list_whiteboards/get_a_whiteboard工具时应优先路由到该专用技能。二、认证行为User OAuth 与 S2S OAuth 的能力差异2.1 User OAuth 是验证通过的读取路径根据本指南关联文档authentication-and-identifiers.md的记录User OAuth用户级 OAuth配合 Whiteboard 专属 Scope 是经过实际验证可工作的路径适用于以下两个读工具list_whiteboardsget_a_whiteboard所需的用户 OAuth Scope 集合为whiteboard:read:list_whiteboardswhiteboard:read:whiteboard这与插件整体的认证基调一致oauth-setup.md 明确说明Zoom MCP 系列的文档化路径是使用 General 应用General App配合用户级 OAuth每位用户以各自的 Zoom 账号授权生成的 bearer token 由捆绑的 connector 通过环境变量注入。Whiteboard MCP 使用的是独立的一套 Scope 集合与主 Zoom MCP 的ai_companion:read:search、meeting:read:search等 Scope 并不相同。2.2 S2S OAuth 的能力边界与典型报错Server-to-ServerS2SOAuth 可以到达 Whiteboard MCP 网关并完成协议发现tools/list但白板读工具的真正执行必须针对你的应用单独验证。也就是说tools/list能成功不代表list_whiteboards/get_a_whiteboard能成功。当 S2S 应用缺少期望的 Scope 时一个可能的运行时错误形态是Invalid access token, does not contain scopes:[whiteboard:read:admin,whiteboard:read]注意这个错误消息里出现的是whiteboard:read:admin,whiteboard:read这样的 Scope 形态这与下面将要介绍的 protected-resource 元数据所宣告的 Scope 并不完全一致进一步印证了不同认证通道下的 Scope 命名/映射可能不同S2S 路径必须实测确认。2.3 Protected-resource 元数据宣告的 ScopeWhiteboard MCP 网关通过 OAuth protected-resource 元数据宣告其支持以下 Scopewhiteboard:write:whiteboardwhiteboard:read:list_whiteboardswhiteboard:read:whiteboard其中写能力的whiteboard:write:whiteboard由 whiteboard/references/tools.md 与 mcp-architecture.md 交叉印证。mcp-architecture 文档还指出托管 MCP 表面会通过 OAuth protected-resource 元数据宣告支持的 Scope这应当作为配置应用的权威参考之一。2.4 实操建议优先使用 User OAuth对接 Whiteboard MCP这是已验证可工作的路径仅在已确认应用能以所需 Whiteboard Scope 铸造并执行 token之后才考虑依赖 S2S在 whiteboard/SKILL.md 中捆绑的 connector 期望 token 通过环境变量ZOOM_WHITEBOARD_MCP_ACCESS_TOKEN注入——这与主 Zoom MCP 的ZOOM_MCP_ACCESS_TOKEN、Docs MCP 的ZOOM_DOCS_MCP_ACCESS_TOKEN是分开的配置时不要混淆。三、OAuth 令牌获取与注入的完整流程虽然本指南的核心是认证行为与 ID 映射但为了让上述 Scope 配置可落地这里结合 oauth-setup.md 给出 Whiteboard MCP 的令牌获取链路创建 General 应用在 Zoom Marketplace 的 Develop → Build App 中创建General app并配置为用户级 OAuth设置回调地址记录 client ID 与 client secret配置 Whiteboard Scope为应用添加whiteboard:read:list_whiteboards与whiteboard:read:whiteboard如需写能力再加whiteboard:write:whiteboard授权并换取令牌构造授权 URL 引导用户授权将回调中的code兑换为 access tokencurl -X POST https://zoom.us/oauth/token \ -u CLIENT_ID:CLIENT_SECRET \ -d grant_typeauthorization_codecodeCODEredirect_uriREDIRECT_URI注入环境变量export ZOOM_WHITEBOARD_MCP_ACCESS_TOKENYOUR_WHITEBOARD_ACCESS_TOKEN之后重启 Claude Code 或重新启用插件使捆绑的 MCP 服务以新 token 重启。令牌生命周期遵循 Zoom OAuth 常规access token 约 1 小时过期refresh token 视为单次使用——每次刷新会返回新的 access token 与新的 refresh token成功刷新后旧 refresh token 即作废且应避免对同一存储 token 发起并发刷新。四、Whiteboard ID 映射从分享链接提取whiteboard_id4.1 核心规则MCP 层面的whiteboard_id对应 URL 中/wb/db/之后的路径段。以本指南文档给出的实例为例https://us05whiteboard.zoom.us/wb/db/6iktP8hJT3e5qaCuwFuAGg/p/180968285929472正确的 MCPwhiteboard_id6iktP8hJT3e5qaCuwFuAGg数字/p/...段180968285929472是页面/子资源标识符不是Whiteboard MCP 标识符。whiteboard/SKILL.md 用更直观的方式标注了这两个段的差异https://us05whiteboard.zoom.us/wb/db/6iktP8hJT3e5qaCuwFuAGg/p/180968285929472 ^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^ whiteboard_id page/subresource id4.2 为什么这个映射至关重要把/p/后面的数字误当成whiteboard_id是集成白板 MCP 最常见的错误之一。这与仓库中反复强调的不要复用猜测的 ID而是重新发现目标原则一脉相承troubleshooting/common-errors.md 在讨论会议资产与录制检索时同样指出应使用实时列表现金返回的标识符而不是假设排期会议编号与录制流程使用同一标识符。对白板而言唯一的权威 ID 来源就是/wb/db/之后的段。五、响应形状不要被工具名误导一个容易被忽视但极其重要的经验get_a_whiteboard实际返回的是列表风格的载荷list-style payload其中包含匹配到的白板而不是一个显而易见的单对象载荷。因此不要因为工具名中带有get_a_就假设返回体是单一对象结构应以实际从实时服务器收到的响应形状为准编写解析逻辑这一原则同样体现在 mcp-architecture.md 的检索模型部分编写解析器时应依据服务器实时的响应形状进行校验而不是依赖过时的示例字段名。六、Whiteboard MCP 工具面与读取工作流6.1 工具目录根据 whiteboard/references/tools.md对应tools/list的实时结果当前 Whiteboard MCP 工具面为工具用途说明create_a_whiteboard_for_brainstorming从头脑风暴输入问题、想法、下一步创建白板调用前需校验请求 schemalist_whiteboards列出当前用户或管理员上下文可访问的白板本指南读取工作流覆盖create_a_whiteboard创建白板调用前需校验请求 schemaget_a_whiteboard按whiteboard_id获取白板本指南读取工作流覆盖create_a_whiteboard_by_script用脚本化内容或结构化输入创建白板调用前需校验请求 schemaupdate_a_whiteboard_metadata更新白板元数据调用前需校验请求 schemacreate_a_whiteboard_for_meeting_summary从会议纪要类输入生成白板调用前需校验请求 schemacreate_a_whiteboard_for_strategy_analysis为战略分析内容生成白板调用前需校验请求 schema注意部分 MCP 客户端会在界面中为服务器工具添加命名空间前缀例如whiteboard-mcp:list_whiteboards请以上述原始工具名为准。6.2 推荐的读取工作流使用带 Whiteboard 读 Scope 的 User OAuth token调用list_whiteboards发现可访问的白板并确认正确的whiteboard_id使用该whiteboard_id调用get_a_whiteboard。按此流程结合第四节中的 ID 提取规则即可在拿到一个白板分享链接后快速构造出正确的读取调用。七、常见认证与调用错误速查结合 error-codes.md 与 common-errors.md针对 Whiteboard MCP 最可能遇到的错误归纳如下症状成因修复Access token is required-32001connector 没有可用 token未发送 Authorization 头设置ZOOM_WHITEBOARD_MCP_ACCESS_TOKEN并重启 Claude Code / 重新启用插件Invalid access token-32001token 过期、被撤销或缺少工具所需的精确 MCP Scope刷新 token核对 Whiteboard 专属 Scope 后重新注入Invalid access token, does not contain scopes:[whiteboard:read:admin,whiteboard:read]S2S 应用缺少期望的 Whiteboard Scope改用 User OAuth或为 S2S 应用补充相应 Scope 后实测验证Can not found tool-32602工具名错误或请求发到了错误的 MCP 表面确认使用 Whiteboard MCP 端点重新执行tools/list获取当前工具名响应解析失败按get_a_whiteboard单对象假设解析列表式载荷以实时服务器返回的实际响应形状为准重写解析器八、小结Zoom Whiteboard MCP 的接入门槛集中在三个容易被误解的点上认证通道选择User OAuth 是已验证路径S2S 需单独验证、标识符提取取/wb/db/之后的段而非/p/后的数字以及响应形状get_a_whiteboard返回列表式载荷。本文全部结论均有仓库内文档与实测记录支撑可进一步阅读whiteboard/references/authentication-and-identifiers.md — 本文核心依据认证行为、Scope 与 ID 映射whiteboard/SKILL.md — Whiteboard MCP 技能入口与工具面总览whiteboard/references/tools.md — 实时工具目录与 Scope 家族concepts/oauth-setup.md — OAuth 应用创建、Scope 配置与 token 生命周期troubleshooting/common-errors.md 与 references/error-codes.md — 错误排查清单。【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考