Workspace MCP 的 OAuth 客户端为何要拆分

变化是什么

Google Workspace 开发者发布说明宣布，自 2026 年 11 月 11 日起，调用 Workspace MCP 服务的应用必须使用已标记为 AI 代理的 OAuth 客户端；未标记的客户端会被拒绝。这个变化针对的是 MCP 请求的客户端身份，不是 Workspace REST API 的统一停用或 OAuth 全面改版。只调用 Gmail、Drive 等 REST API、并不作为 AI 代理运行的集成不受这项规则影响。对于一个客户端同时承担代理与普通应用功能的系统，官方给出的迁移方向是保留原客户端供非代理功能使用，另建一个标记为 AI 代理的客户端供 MCP 使用。

这条边界很重要：MCP 工具调用可能让模型代表用户执行读写操作，OAuth 客户端因此不仅是“拿 token 的配置项”，还成为服务端识别调用属于哪类应用的身份信息。OpenID Foundation 关于 Agentic AI 身份管理的报告也把代理软件身份与用户身份、授权委托分开讨论。Workspace 的做法，是在 OAuth 客户端层明确标出代理用途，再由用户授权其具体权限。它不是让“标记为代理”取代 scope、用户同意或组织策略。

先判断请求走哪条路径

排查前先把调用链按协议分开。若程序请求 https://gmail.googleapis.com/、Drive REST API 或其他 Workspace REST 端点，它走的是对应 API 的 OAuth 授权路径；单凭这次客户端标记公告，不应推断它会因此被拒。若 AI 客户端连接 https://gmailmcp.googleapis.com/mcp/v1 等 MCP 端点，且凭据来自 Google Auth Platform 中创建的 OAuth 客户端，就需要检查该客户端的 agentic 标记。

Workspace MCP 配置文档列出 Gmail、Drive、Docs、Sheets、Slides、Calendar、Chat、People 与 Classroom 等独立 MCP 服务端。连接远程服务需要在项目中启用相应 API 和 MCP 服务，并由 MCP 客户端通过 OAuth 2.0 授权。仅仅把 MCP URL 填入客户端配置，并不能证明授权侧已满足准入要求；服务端 URL、OAuth client ID、授权 scope 和客户端标记属于不同检查项。

官方发布说明写明 2026 年 11 月 11 日开始拒绝未标记客户端的 MCP 请求，并称截至 11 月 12 日仍未标记的客户端会继续保持非 agentic 状态，之后若要使用 MCP，需要创建新的 agentic OAuth 客户端并更新应用。开发团队不应把这两天理解成自动转换窗口：文档没有承诺服务端会替旧客户端补标记，也没有承诺旧授权 token 会自动换绑新 client ID。更稳妥的工程安排是把新 client ID 的部署与用户重新授权作为明确迁移步骤，并在截止日期前完成验证。

为什么要拆分客户端

假设一个 Web 应用既提供用户手动操作的管理界面，又把同一组 OAuth 凭据交给后台 AI 代理访问 MCP。继续共用一个客户端，看上去少一份配置，但会把两类调用方身份绑定在一起。Google 的发布说明建议这类混合应用保留普通客户端，再为 AI 代理创建单独客户端，只给代理客户端标记用途。这样 REST API 的既有登录流程与代理 MCP 的新准入要求可以分别管理。

拆分的第二个原因是该标记不是一个可以随时翻转的运行期开关。Google Chat 的 OAuth 配置指南针对支持该标记的客户端类型指出，创建客户端时可以选择 “Use this client for an AI-powered agent”，而客户端创建后不能更改这一设置。对已经创建的客户端，不能假定进入控制台后能补选；需要确认控制台实际提供的能力。若无法更改，应新建正确类型的客户端，并把新 ID 接入 MCP 客户端配置。

拆分不等于复制一套所有权限。新客户端仍应只请求业务需要的 Workspace scopes；agentic 标记回答的是“这个 OAuth 客户端是否用于 AI 代理”，scope 则回答“用户授权访问哪些数据和操作”。两者不能互相替代。部署时要核对授权同意屏幕、测试用户或组织受众配置、重定向 URI、MCP 服务启用状态，以及用户实际同意的 scope。任何一项缺失，都可能表现为连接失败，但修复方向并不相同。

按应用类型迁移

使用 Antigravity 或其他 MCP 客户端的应用，可先在 Google Auth Platform > Clients 中创建 OAuth 客户端，应用类型和回调地址按客户端文档及实际 MCP 客户端要求配置，并在创建时选中 AI 代理标记。之后将新 client ID 和相应凭据更新到 MCP 客户端配置，再执行一次真实授权。Google Workspace 配置指南给出的远程 MCP 传输是 Streamable HTTP，每种产品有自己的 MCP URL；不要把示例中的 Gmail 地址误当成所有服务共用的端点。

如果一个产品还需要直接调用 REST API，可以把非代理调用继续留在旧客户端，新客户端只服务 MCP 代理。代码和部署配置应显式区分 workspace_rest_oauth_client_id 与 workspace_mcp_oauth_client_id 这类用途，而不是让一个含义模糊的环境变量在多处复用。密钥管理、回调地址、token 缓存与撤销流程也应按客户端身份分别盘点，避免滚动部署时把用户已有授权误认为已授权新 client ID。

Apps Script 有特别限制：脚本默认 OAuth 客户端由 Apps Script 管理，不能在 Google Auth Platform 的客户端列表中选择 AI 代理标记。Workspace MCP 配置文档给出的方式是另建一个已标记的 OAuth 客户端，通过 OAuth2 for Apps Script 库完成用户授权，并在 MCP 请求中使用该库返回的 access token，而不是 ScriptApp.getOAuthToken()。只有调用 MCP 的脚本需要这条改造；不调用 MCP 的 Apps Script 项目不受影响。

使用带有 domain-wide delegation 的服务账号也要区别处理。服务账号不由 Google Auth Platform > Clients 管理，因此不能勾选同一客户端标记；官方配置文档说明，这类请求不会因缺少该标记而按此规则拒绝，其访问仍由 Workspace 管理员配置的全域委派控制。不要把服务账号例外扩展为“服务账号不受其他安全策略约束”，委派范围和组织访问策略仍然适用。

验证与故障定位

迁移后至少分别验证三个结果：OAuth 流程是否返回访问令牌；令牌是否带有预期 scope；MCP 客户端是否能对目标服务端完成初始化并调用一个只读工具。然后再验证写操作，并在生产数据之外使用受控测试账号。MCP 连通不表示所有工具都可用，工具授权也不表示 REST API 调用路径已同步迁移。

若请求被 MCP 服务端拒绝，先从 OAuth 日志确认实际使用的 client ID，而不是只看配置文件里“新 ID 已写入”。再确认该 ID 是新建且在创建时标记为 AI 代理的客户端，MCP 进程没有继续读旧环境变量，用户已完成新客户端的授权，并且请求打到了对应 Workspace 产品的 MCP URL。若系统仍通过旧客户端执行普通 REST API，则该旧身份继续留给 REST 路径，不要为了让 MCP 通过而把所有调用盲目改到新客户端。

若故障发生在 Apps Script，检查 MCP 请求的 bearer token 是否来自 OAuth2 库，而不是脚本默认 token；若调用身份是服务账号，则检查管理员的 domain-wide delegation 配置，不要寻找一个并不存在的客户端复选框。若只是 access token 到期后频繁要求用户重新登录，Workspace MCP 文档另指出，Google OAuth 返回 refresh token 需要授权请求带 access_type=offline；仅请求 OIDC offline_access 不会得到该 refresh token。这个续期问题与 agentic 标记是两条独立配置线，应分别处理。

上线前检查

可以把迁移拆成一次可回滚的身份切换：先创建代理专用客户端，保留旧客户端；在测试环境完成重新授权和 MCP 工具验证；部署端按用途切换 client ID；最后分别检查 MCP 与 REST API 的日志和用户授权状态。回滚时也要明确恢复哪个 client ID，避免服务端配置回滚而用户端仍持有另一客户端的授权状态。

如果应用仅使用 Workspace REST API，不需要为了这条公告创建 MCP 客户端。若应用确实使用 MCP，则把标记作为创建 OAuth 客户端时的设计决策，而不是上线后再补的标签。可以继续阅读 MCP 按需升级授权的边界，并从平台目录查看其他 API 接入资料；这些内容不能代替 Workspace 自身的 OAuth 配置和组织策略。

截至 2026 年 11 月 5 日，Google Workspace MCP 仍处于 Developer Preview。本文涉及的准入时间、迁移方式和例外均以当天可访问的官方文档为准；实际项目应在发布和部署前重新检查官方页面是否有更新。