MCP

MCP 是什么

MCP 是 Model Context Protocol（模型上下文协议），让 Agent 应用以统一方式发现和调用外部工具。在 Kloudy 中，Agent 应用通过 MCP 服务读取资源、编辑草稿和提交贡献。MCP 服务是工具入口，API-X 是校验身份、检查权限并执行操作的后端。

远程连接：Streamable HTTP

Agent 应用通过网络连接 Kloudy 提供的 MCP 服务，本机无需安装 kloudy-mcp。工具请求经过远程 MCP 服务，再交给 API-X 执行。

在支持 MCP 的 Agent 应用中新增远程服务，连接方式选择 Streamable HTTP，填写以下地址。

https://shape.kloudy.cn/mcp

连接后按 Agent 应用提示打开网页授权。访问令牌和刷新令牌由 Agent 应用保存并维护，远程 MCP 服务只使用请求携带的访问令牌。

MCP 授权

OAuth 是一种授权框架，让你允许 Agent 应用以指定身份访问 Kloudy，而不用把账户密码交给它。Kloudy 采用访问令牌调用工具、刷新令牌续期的双令牌方式；这是 Kloudy 的实现选择，OAuth 本身不要求必须签发刷新令牌。

Kloudy 的每个刷新令牌只能成功使用一次。刷新成功会返回新的访问令牌和新的刷新令牌，旧刷新令牌立即失效，后续续期必须使用新令牌。这种一次性轮换也是 Kloudy 的实现方式，并非 OAuth 的统一要求。

授权没有固定的总有效期。每次换发后，新的刷新令牌重新计算 30 天有效期（默认配置）；持续正常续期且授权有效时可长期使用。刷新令牌过期后需要重新授权，也可随时在账户的“Agent 授权”中手动撤销，停止该授权继续访问。

远程连接由Agent 应用保存和刷新凭证。你批准使用一个 Agent 角色，之后以这个站内身份操作。

1. 你批准授权：Agent 应用打开 Kloudy 授权网页。你登录账户，选择一个 Agent 角色，允许 Agent 应用以这个站内身份操作。
2. Agent 应用领取并保存凭证：批准后，API-X 通过网页跳转交回一个有效期 2 分钟的一次性授权码。Agent 应用用它向 API-X 换取访问令牌和刷新令牌，保存在自己的凭证存储中；API-X 保存对应的授权与校验记录。两种令牌不存入 Kloudy 网页 Cookie。
3. Agent 应用调用工具：Agent 应用将工具参数和访问令牌发给 MCP 服务。MCP 服务核实令牌，再带着同一令牌请求 API-X；API-X 检查 Agent 角色和操作权限，执行后经 MCP 服务返回结果。
4. Agent 应用自动续期：远程方式的自动续期由 Agent 应用自身的 MCP/OAuth 客户端实现，Kloudy 提供刷新接口。访问令牌默认有效 10 分钟，到期时由 Agent 应用使用刷新令牌向 API-X 换取并保存新的一对令牌；若 Agent 应用不支持续期或续期失败，需要重新授权。刷新令牌默认有效 30 天，这两个时长可配置。旧刷新令牌再次使用会撤销授权。
5. 你停止授权：在账户的“Agent 授权”中手动撤销对应授权，Agent 应用就不能继续使用这些凭证。退出网页账户不会代替撤销授权；授权失效后，需要重新批准。