客户端接入

状态

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

1. 先检查身份与订阅权益

MCP 是付费增值服务。连接前请确认：

1. 使用当前租户的超级管理员（SUPERADMIN）账号；普通管理员或员工不能授权，角色名称不能代替资格校验。
2. 当前租户已启用，主套餐为 ACTIVE。
3. 确认同一租户已有有效 MCP 订阅权益。若主套餐未明确包含 MCP，到主站 服务订阅 → 增值市场（/service-subscription?tab=market）购买，再返回客户端授权。

单独加购 MCP 时，按年复购增加时长而非调用次数；权益有效截止为已购 MCP 截止与主套餐截止的较早者。 主套餐续订可解锁尚未到期的已购时长，但不会暂停或重置 MCP 计时。规则见MCP 是什么。

2. 检查客户端兼容性

仅支持远程 MCP / Streamable HTTP 并不足够。 客户端还需支持：

• 根据 401 的 WWW-Authenticate 完成受保护资源及授权服务器发现；
• OAuth 动态客户端注册；
• 浏览器授权码流程与 PKCE S256；
• 保存令牌、使用刷新令牌续期，并保存轮换后的新刷新令牌。

Claude、Cursor 等客户端的功能受版本和配置影响；不能仅凭客户端名称判断兼容。 本页使用 OAuth，不提供 AppKey 配置 MCP 的接入方式。

3. 配置端点并授权

环境	MCP 端点	接入前确认
生产	https://open.risemap.cn/v1/mcp	按该环境发布记录确认
开发	https://open-dev.risemap.cn/v1/mcp	确认联调服务及配置

在客户端的远程 MCP / 自定义连接器设置中填入对应环境端点。支持以下配置结构的客户端可参考：

{
  "mcpServers": {
    "risemap": {
      "url": "https://open.risemap.cn/v1/mcp"
    }
  }
}

配置字段以客户端实际支持为准。兼容 OAuth 的客户端无需手工配置密钥或 Authorization 请求头； 它会发现授权入口并打开浏览器。不出现授权页时，先查兼容性、端点和网络，不要复制主站登录令牌到配置中。

授权过程：

1. 客户端动态注册，生成 PKCE 校验对并打开 Risemap 授权页。
2. 登录并确认当前租户；服务端校验超级管理员身份、主套餐与 MCP 权益。未满足条件先处理，不是点“同意”即可开通。
3. 勾选授权范围：读权限默认勾选，写权限默认关闭，只开启必要范围。
4. 同意后返回客户端，完成授权码交换；授权页预检、首次换 token 和每次 refresh 仍会远程核验收费，首次换 token 与 refresh 的既有校验不变。

access token 默认有效期 7200 秒（2 小时，可配置），由客户端发起 refresh，并非服务端定时刷新。 已签发 token 的收费通过结果固定缓存至该 token 自身到期，命中不续期；正常 MCP 请求不远程查询 PM，但仍校验凭证及当前管理员 / 租户状态。 旧 token 或缓存丢失时，首次使用补验一次，成功后仅缓存至原到期时间。AppKey 没有 refresh，采用固定 2 小时收费缓存，命中不续期，到期后下次调用补验；这不表示本页支持 AppKey 配置 MCP。

首次换 token / refresh 已实时核验收费并成功签发后，仅辅助 paid marker 写入失败时记录日志，仍返回已签发 token，不改报 503；客户端应使用新 token，不重放已消费的授权码或已轮换的 refresh。后续 MCP 请求在 marker 缺失时补验，请求侧 Redis 读写故障仍返回 503。

4. 验证能力

连接成功且准入通过后，tools/list 应有 list_domains、search_apis、describe_api、call_api 四个元工具。 先列业务域，再搜索和描述接口；业务接口范围与授权人权限共同限制 AI 的实际能力。 执行写操作须先获用户明确同意，详见工具与能力。

排查

现象	处理
授权页提示不满足条件（INACTIVE）	检查当前租户、超级管理员资格、主套餐 ACTIVE 及同租户有效 MCP 权益；先购买或恢复资格再授权
授权页暂不可校验（UNAVAILABLE）	等待服务恢复，不要把未知状态当作未购买，也不要反复购买或授权
授权请求不存在或已过期	授权页停留超过 10 分钟，回到客户端重新发起连接
元工具列表为空 / 未出现四个工具	检查 OAuth 兼容性、授权结果、环境端点及服务状态；不是“没有开放业务接口”
list_domains / search_apis 返回空结果	检查授权 scope、关键词和 domain，以及当前环境已启用的接口清单
401 / 一直要求重新授权	检查令牌及当前租户超级管理员资格、员工和租户启用状态；资格恢复后再授权，不是无条件重新登录即可
403 access_denied	MCP 权益准入未通过；检查主套餐及 MCP 有效期、所属租户，不要自动重试或重复授权
503 temporarily_unavailable	身份服务、MCP 请求侧 Redis 缓存、收费配置或需要远程核验时的 PM 暂不可用；按 Retry-After（5 秒）等待，持续出现时联系运维，不应要求重新购买
订阅到期 / 取消后，旧 token 暂时仍可调用	收费通过结果缓存至该 token 到期，最长延迟一个 access token 有效期才拒绝；不是延期权益或永久豁免
PM 故障期间，已有连接仍可调用	可读取的有效收费缓存不需查询 PM；刷新 / 补验仍可能返回 503，身份链也必须正常

HTTP 状态与工具内业务错误须分别处理，见错误码。网络超时或写入结果未知时，先查询业务状态，不能盲目重试。

撤销与资格变化

主站 「我的授权」（/oauth/connections，授权页底部也有入口）可查看和撤销 AI 工具授权； 撤销即时吊销该授权的令牌，再使用需重新授权。

每次 MCP 请求都检查凭证与当前身份。丧失超级管理员资格、员工禁用 / 离职、租户禁用后， 已有令牌也不能继续调用，不必等到下一次刷新或收费缓存到期才拒绝。

收费到期 / 取消则按缓存边界生效：OAuth 最长延迟一个 access token 有效期（默认 2 小时，可配置），AppKey 最长延迟固定 2 小时。 该延迟不适用于撤销授权或身份失效，不改变年度权益截止日期。MCP 请求侧 Redis / PM 无法核验时拒绝，不免费放行，详见认证与授权。