Herald

用 OAuth 把 Claude Code、VS Code 等 MCP 客户端接入 Herald 租户——无需 API Key、无需 client secret。浏览器登录一次，即可通过九个只读工具查询你的租户。

Herald 提供官方 MCP（Model Context Protocol）服务，你的 AI agent 可以用结构化的工具语义查询租户数据，而不必阅读 REST 文档后手写调用。授权走 OAuth：你在浏览器里用自己的 Herald 账号登录一次，agent 持有用户凭证——不需要 API Key，不需要 client id，也不需要粘贴任何 secret。

端点是标准 MCP Streamable HTTP 端点（协议版本 2026-07-28），由你的 Herald 实例自身提供——与 REST API 同源，无需独立部署。Herald 的 MCP 服务不接受 API Key。

1. 获取租户地址

每个租户有唯一的 canonical MCP 地址：

https://<origin>/mcp/<realmId>

<origin>——你的 Herald 部署源（或租户配置的自定义域名）
<realmId>——你的租户 ID

租户 ID 是地址的一部分：为一个租户签发的凭证拿到另一个租户的地址上必然失效。

2. 连接你的 Agent 客户端（仅需 URL）

客户端只需要租户地址，不需要其他任何输入。客户端会通过 RFC 9728 / RFC 8414 发现与受控的 RFC 7591 注册端点，自动取得本租户预置的公共 MCP 客户端（herald-mcp）。

先开启租户的 MCP 接入：内置的 Herald MCP 客户端默认停用。租户管理员需先在管理后台 Client App 列表中启用它，agent 才能完成注册与授权（见第 7 节的租户开关）。

Claude Code——已在 Claude Code 2.1.269 上完成端到端验证：仅凭 URL 即可完成注册、浏览器授权、工具发现与工具调用。

claude mcp add --transport http herald https://your-herald-host/mcp/your-realm-id

VS Code（.vscode/mcp.json，或 MCP: Add Server → HTTP）——消费与上面验证过的同一套发现与注册契约（已对照 VS Code 1.140 检查）；VS Code 内的交互式 OAuth 握手尚待端到端验证。

{
  "servers": {
    "herald": {
      "type": "http",
      "url": "https://your-herald-host/mcp/your-realm-id"
    }
  }
}

其他实现了 MCP 授权规范（受保护资源发现、浏览器 PKCE 授权、动态客户端注册）的 MCP 客户端应可同样接入——同样只填租户地址。

工具	作用	所需权限
`query_users`	查询租户用户列表或详情	`users.view`
`get_points_balance`	指定用户的租户范围积分余额	`points.view`
`list_points_transactions`	指定用户的积分流水，最新在前	`points.view`
`list_audit_logs`	查询租户审计日志	`audit.view`
`get_realm_config_status`	查询各配置项的存在与启用状态	`settings.view`

管理余额工具返回的是目标用户整个租户范围的余额，不按 client app 收窄。配置状态在任何情况下都不返回配置值。

本人工具

一律只作用于授权用户本人。这些工具不接受 userId——要求查询他人会被拒绝：

工具	作用	所需 scope
`get_my_profile`	我的资料	`mcp:profile:read`
`get_my_points_balance`	我的积分余额	`mcp:points:read`
`list_my_points_transactions`	我的积分流水	`mcp:transactions:read`
`list_my_subscriptions`	我的订阅与权益状态	`mcp:subscriptions:read`

任何被授予对应 scope 的 Herald 用户都可以调用本人工具——不需要管理员角色。

共同约定

分页从 1 开始，默认 page=1 / pageSize=20，最大 100。
时间过滤接受 RFC 3339 时间戳或 YYYY-MM-DD（按 UTC 零点解释）。
返回字段刻意收窄——agent 可能把结果带入第三方模型：不透出 IP、User Agent、Trace ID、配置值或支付元数据。
只读是刻意设计。写操作被有意排除，只会在逐工具安全评审后按工具逐步加入。需要写入数据或完整字段面时，请改用客户端凭证调用 REST API——参见第三方后端集成指南与 OpenAPI 参考。

5. 连通性自检

连接完成后，让 agent 执行：

使用 herald 的 get_my_profile 工具。

该工具零入参、只读取你本人的资料、除 profile scope 外不需要任何管理权限。成功返回你的 id 与邮箱，即证明「发现 + 客户端注册 + 浏览器授权 + 取数」全链路可用。

6. 排障

症状	原因	恢复方式
工具返回 `permission_denied`——"Your user does not have the 'X' permission"	管理工具按授权用户的 RBAC 放行	请租户管理员为你授予带该权限的角色；重新登录无效
HTTP 403 且带 `insufficient_scope` 挑战	本次授权未授予本人工具所需 scope	在 agent 客户端重新授权，并接受请求的 scope
每次调用都返回 HTTP 401 授权挑战	凭证缺失、过期或被吊销——或租户已停用 MCP 接入	重新授权；若租户停用了 MCP，请管理员重新启用后再重新授权（旧授权不会复活）
连接时 HTTP 404	租户地址不对	检查 `https://<origin>/mcp/<realmId>`——含租户 ID，无尾斜线
`invalid_target` / `invalid_scope` 错误	授权请求被篡改或客户端配置有误	删除后仅用租户地址重新添加服务
工具返回 `not_found`	目标 id 不存在——或属于其他租户（跨租户 id 一律表现为 not found）	检查 id；agent 无法查询授权租户之外的数据
工具返回 `invalid_argument`	参数畸形——错误信息会指明字段与期望格式	按提示修正后重发（如合法 UUID、`startTime` 不晚于 `endTime`）
工具返回 `internal_error`	服务端故障	重试；持续出现请查看服务端日志

7. 凭证、隔离与限额

凭证双向隔离： MCP 凭证代表你本人，但与浏览器/管理台会话相互独立——两侧互不接受对方凭证。
长会话： 客户端通过标准刷新授权续期；refresh token 轮换且有绝对上限。
即时吊销： 账号被禁用、被强制下线或租户内置 MCP 客户端被停用的那一刻，你的 MCP 凭证立即失效。
租户开关： 每个租户在管理后台 Client App 列表中有一个内置的「Herald MCP」客户端。停用即关闭本租户 MCP 接入——已有与新增授权全部被拒绝。重新启用不会复活旧授权，agent 需重新授权。内置客户端不可删除。
限流： 每个授权用户的 MCP 调用限额为 60 次 / 60 秒。

MCP 集成（AI Agent 接入）

1. 获取租户地址

2. 连接你的 Agent 客户端（仅需 URL）

3. 浏览器登录一次

4. 九个只读工具

管理工具

本人工具

共同约定

5. 连通性自检

6. 排障

7. 凭证、隔离与限额

On this page