MCP 是什么

状态

本文说明当前代码实现的接入规则，不代表各环境已发布或可用。实际接入前请确认目标环境的发布状态与配置；文档站可访问不等于 API / MCP 服务已就绪。

简介

MCP（Model Context Protocol）让 AI 客户端调用外部能力。接入后，可在兼容客户端中查询和操作 Risemap 数据，无需逐个对接业务接口。MCP 是付费增值服务，有效订阅权益与 OAuth 授权缺一不可；套餐明确包含 MCP 时不要求重复加购。

仅限当前租户的超级管理员（SUPERADMIN）；普通管理员、普通员工不适用，也不按角色名称中是否含“管理员”判断。
当前租户须启用，主套餐状态为 ACTIVE，且同一租户的 MCP 权益有效；其他租户的身份或购买记录不能代用。
先确认当前套餐是否明确包含 MCP；未包含时在 Risemap 主站 服务订阅 → 增值市场（/service-subscription?tab=market）购买 MCP，再由该租户超级管理员完成 OAuth 授权。价格与可购规则以市场页面为准。
客户端必须兼容远程 MCP 及完整 OAuth 流程，不能只看是否支持 Streamable HTTP。详见客户端接入。

主套餐必须为 ACTIVE 且处于有效起止时间内，不在此额外限定为付费主套餐或排除试用；具体可购资格以实际策略校验为准。

当前实现也认可主套餐明确包含的 MCP 资源权益；这不代表任意主套餐都包含 MCP。历史加购余额或手工调增额度不能单独证明已购权益仍有效，技术判定见认证与授权。

以下为单独加购 MCP 的有效期规则；套餐内含权益按主套餐资源策略核验。MCP 加购按年购买，复购增加服务时长，不是调用次数。有效期由两个日期共同决定：

effectiveEnd = min(paidEnd, mainEnd)

paidEnd：已购买 MCP 时长对应的固定截止日期；mainEnd：主套餐截止日期。
主套餐较早结束时，权益有效截止为 mainEnd。后续续订主套餐，可在尚未到期的 paidEnd 范围内延长可用期；不会自动增加 MCP 已购买时长。调用期的收费缓存延迟不改变这一截止日期。
已购时长尚未耗尽时复购，延长原 paidEnd；已耗尽后复购，从本次购买生效时开始新周期。
日期按自然时间推进，不是停用时暂停计时、恢复后补回天数。即使截止日期尚未来临，也仍须满足租户启用、主套餐 ACTIVE 等条件。

MCP 是开放平台的消费方，不是平行的另一套系统。

AI 客户端 → MCP（OAuth / Streamable HTTP）→ 开放 API 平台 → 各业务微服务

MCP 与 REST 共用凭证、scope、权限与审计基础，但 MCP 另有付费权益准入。本文 MCP 接入方式为 OAuth；AppKey 的 REST 接入说明不等于支持用 AppKey 配置 MCP。

在身份及权益准入通过后，agent 能做的 = 授权范围 ∩ 授权人本人的权限。每次 MCP 请求仍校验凭证、当前超级管理员资格与租户状态；正常调用命中有效收费缓存时，不远程查询 PM。

OAuth 授权页面预检、首次授权码换 token、每次 refresh，仍远程核验收费权益。
access token 默认有效期 7200 秒（2 小时，可配置）；刷新由客户端发起，不是服务端定时 refresh。
已签发 token 的收费通过结果缓存至该 token 自身到期，命中不续期、期限不滑动。旧 token / 缓存丢失时首次使用补验一次，成功后只缓存至原到期时间。
收费到期 / 取消的拒绝，最长可延迟一个 access token 有效期；这不是补发已购天数，也不是管理员降权、撤销授权或租户禁用的宽限。
AppKey 没有 refresh；请求 MCP 的收费通过结果固定缓存 2 小时，命中不续期，到期后下次调用补验。不影响普通 REST。
首次换 token / refresh 已实时核验收费并成功签发后，仅辅助 paid marker 写入失败时记录日志，仍返回已签发 token，不改报 503；后续 MCP 请求在 marker 缺失时补验。
MCP 请求侧 Redis 无法安全核验缓存，或需要补验时 PM 不可用，返回 503，不免费放行。已有可读取的有效收费缓存不受 PM 故障影响；身份链故障仍可能拒绝调用。

详细边界见认证与授权。

鉴权与准入通过后，tools/list 固定返回 4 个元工具，不会把业务接口全量平铺：

业务接口搜索为空不等于元工具列表为空。完整签名与写操作安全要求见工具与能力。