MCP 接入文档 | Manager AGI

授权登录回传

安装 SDK：

pnpm add mcp-auth-web

API 环境（engineUrl 填以下地址，不带路径）：

测试环境: https://aim-api-test.proton-system.com
正式环境: https://aim-api.proton-system.com

完整授权回跳地址: https://xxx.com/openapi/v1/mcp/authorization/callback

SDK 自动补上此路径，无需自行拼接。

登录成功后回传凭据：

import { createMcpAuthClient } from 'mcp-auth-web'

const mcpAuth = createMcpAuthClient({
  engineUrl: 'https://aim-api-test.proton-system.com',
})

mcpAuth.complete({
  Authorization: `Bearer ${token}`,
})

登录失败或用户取消时：

mcpAuth.fail({ code, message })
mcpAuth.cancel()

mcp-auth-web@0.3.1 起，SDK 通过 getMcpAuthErrorMessage(error) 统一提供安全的默认中文错误提示；业务系统只负责展示，也可根据错误码自定义文案或翻译。complete()、fail()、cancel() 的异常都应捕获，不要在 complete() 的 catch 中再次无条件调用 fail()。不要展示或记录原始异常中的凭据和授权 URL。

import { getMcpAuthErrorMessage } from 'mcp-auth-web'

try {
  mcpAuth.complete({ Authorization: `Bearer ${token}` })
} catch (error) {
  message.error(getMcpAuthErrorMessage(error))
}

engineUrl 是平台提供的 Engine 地址。complete 直接接收 MCP 实际使用的凭据 Header；SDK 会从 Authorization 的 Bearer JWT 中读取 exp 并自动生成 expiresAt，调用方无需传入过期时间。

SDK 会自动选择 HTTPS 回跳或现有 App 授权窗口。mcp-auth-web@0.3.0 调整了 complete 的输入格式；从旧版升级时应移除 headers 包装和手动传入的 expiresAt。未配置 engineUrl 时继续使用现有 App 授权窗口。

如果方法返回 false，说明当前页面没有可用的授权回传方式：

if (!mcpAuth.isAvailable()) {
  message.error('当前环境不支持授权回传')
}

验证方法：在 App 中发起授权并完成登录；自动回到 App 且显示“已授权”即表示接入成功。生产登录页和 Engine 地址必须使用证书有效、设备可访问的 HTTPS。不要在日志、分析或错误上报中记录凭据或授权地址。

Tool 通用风险标记

读操作 Tool：

annotations: {
  readOnlyHint: true
}

写操作 Tool：

annotations: {
  destructiveHint: true
}

Tool 类型

1. 列表 Tool

如果 Tool 返回一组候选项，供用户选择后回填到其他 Tool 参数里，需要在 outputSchema 根节点加：

outputSchema: {
  type: "object",
  properties: {...}, // 可以不要
  "x-prerequisiteCandidate": {
    itemsPath: "data",
    valuePath: "id",
    labelPath: "name"
  }
}

这三个字段的意思：

itemsPath: 从 Tool 返回结果里，哪里是候选列表数组。
valuePath: 从每个候选 item 里，哪个字段作为最终回填值。
labelPath: 从每个候选 item 里，哪个字段展示给用户看。

比如 Tool 返回：

{
  "data": [
    { "id": "1", "name": "门店 A" },
    { "id": "2", "name": "门店 B" }
  ]
}

那么：

itemsPath: "data" 表示候选列表是返回结果里的 data 数组。
valuePath: "id" 表示用户选中后，把 item 里的 id 回填给目标 Tool。
labelPath: "name" 表示选择卡上展示 item 里的 name。

约定

列表 Tool 加 x-prerequisiteCandidate。
详情 Tool、写操作 Tool 不加 x-prerequisiteCandidate。
读操作 Tool 加 readOnlyHint: true。
写操作 Tool 加 destructiveHint: true。
列表没有数据时也请返回稳定结构，例如 {"data":[]}。
Tool 实际返回结构要和 x-prerequisiteCandidate 对得上。

MCP Tool 接入规范

授权登录回传

Tool 通用风险标记

Tool 类型

1. 列表 Tool

约定