诚现广告机CXPlayer

简体中文

English

简体中文

English

主题

AI 助手接入（MCP） ​

把管理账号的 API Key（API 密钥）和本页面链接发给 Agent，让它按照教程配置 MCP，就可以用自然语言管理设备、节目和素材。

推荐使用已部署的云端 MCP（Streamable HTTP），无需下载 MCP 程序，也无需在本机启动服务。本地图片、视频等文件也可以由 Agent 直接上传到对象存储，再加入素材库。

Agent 是什么？常见的有哪些？ ​

Agent（AI 智能体）可以理解你的要求，并调用工具替你完成任务。 你可以把它理解为“会使用工具的 AI 助手”。例如，你说“查一下哪些设备离线了”，它就能通过 MCP 连接本系统，查询设备后用你能看懂的话回答。

你可能已经接触过这些 AI 助手或 Agent 工具：

  • ChatGPT、Claude：通过对话使用的 AI 助手。
  • WorkBuddy、Claude Code、Codex：可在电脑上使用的 AI 工作助手或任务执行工具。
  • Cursor、TRAE、Cline：带有 Agent 能力的编程工具。

本文后面说的“把信息发给 Agent”，就是指发到你使用的这类工具的对话窗口中。能否接入本系统，取决于所用客户端或版本是否支持 Streamable HTTP MCP 和本页的 API Key 认证；自动配置、本地文件读取等能力也会因客户端而异。

下面的截图只保留相关操作区域。

第一步：获取 API Key ​

1. 登录管理端，打开“API 密钥” ​

打开你正在使用的网页管理端，登录自己的联网账户。点击账户头像，在弹出的菜单中选择“API 密钥”；也可以从“账户设置”进入。

请确认当前是联网账户。内网服务账号生成的密钥不能用于访问云端账号的数据。

点击账户头像后，在菜单中选择 API 密钥

2. 点击“生成”，填写用途和有效期 ​

进入“API 密钥”页面，点击右下角的“生成”按钮，打开填写窗口：

API 密钥页面右下角的生成按钮

  • 描述：填写容易识别的用途，例如 MCP Agent；多个 Agent 可以分别创建密钥。
  • 过期时间：按使用周期选择，例如 30 天；临时试用可选择更短时间。
  • 启用 API 密钥：保持开启。

生成 API 密钥窗口：描述为 MCP Agent，开启密钥，有效期为 30 天

确认后点击“生成”。

3. 复制并保存完整密钥 ​

在“API 密钥已生成”窗口中点击“复制 API 密钥”，保存后再点击“我已保存，关闭”。

完整密钥只显示这一次。关闭后，列表只能管理密钥，不能再次查看完整值。如果忘记保存，重新生成一把，并停用不再使用的旧密钥。

只提供给可信 Agent

API Key 继承所属账号的权限。只需向可信 Agent 提供这把专用密钥，不需要提供管理账号的登录密码；不要把密钥放进公开文档、截图或代码仓库。不再使用时，可回到此页面禁用或删除。

第二步：把 API Key 和本页面链接发给 Agent ​

打开你使用的 Agent，例如 WorkBuddy、Claude Code 或 Codex，确认它支持 Streamable HTTP MCP 和本页的 API Key 认证。把下面这段话发给它，替换其中的两个占位内容即可：

text
请帮我配置这个信息发布系统的云端 MCP。

教程链接：<复制当前教程页面的完整链接>
API Key：<粘贴刚才复制的完整密钥>

请先阅读教程，再按你当前客户端的配置格式完成接入。
使用 Streamable HTTP，并按教程设置服务地址和认证请求头。
请保留其他已有 MCP 配置，不要在回复或日志里展示完整密钥。
配置后验证连接，并查询当前账号和设备列表。

发送的是本篇教程的完整链接，不是网页管理端地址，也不是 MCP 服务地址。链接中不要附加 API Key。

Agent 会根据自身客户端完成配置。如果它无法修改配置，会给出需要粘贴的配置内容；按提示操作即可。部分客户端需要重新连接 MCP 或重启后才会加载新配置。

第三步：确认连接，开始使用 ​

配置完成后，可以对 Agent 说：

  • “列出我的所有设备，告诉我哪些在线。”
  • “查看这台设备的软件版本和当前节目。”
  • “查一下这个节目投放到了哪些设备。”
  • “把这张本地图片上传到素材库，告诉我素材 ID。”

连接验证只需查询，不需要绑定设备、修改节目或执行投放。 Agent 查询到的是 API Key 所属账号有权访问的数据；账号下还没有设备时，列表为空也属于正常结果。

上传本地图片、视频等素材 ​

告诉 Agent 文件位置，以及希望保存的素材名称即可。例如：

text
请把本机“下载”目录里的 poster.jpg 上传到素材库，名称叫“门店海报”。
完成后告诉我素材 ID，暂时不要创建节目或投放。

Agent 需要能读取这个文件，并在文件所在环境运行 curl 或上传脚本。文件会从 Agent 所在环境直接上传到对象存储，文件内容不经过 MCP 服务，不需要向 Agent 提供对象存储 AK/SK。

如果 Agent 运行在远程环境，它不能直接读取你电脑上的路径。请使用该 Agent 支持的文件提供方式；没有文件读取或本地执行能力时，可以先在管理端上传，再让 Agent 查询素材库。

返回素材 ID 才表示已加入素材库。 文件传输完成不等于入库完成；素材入库也不会自动创建节目或投放。

供 Agent 读取的接入信息 ​

以下信息供 Agent 自动配置和排障使用，普通用户无需手工填写请求头或编写脚本。

云端 MCP 地址与认证 ​

  • 传输方式：Streamable HTTP。
  • 地址规则：以用户提供的本篇教程 URL 为准，保留协议和主机名，将端口设为 9394、路径设为 /mcp。不要把教程路径、管理端 /cx 路径或原文档端口带入 MCP 地址。
  • 如果部署方提供了单独的 MCP 地址，以部署方地址为准。

当前文档站点对应的默认地址：

http://127.0.0.1:9394/mcp

必须携带以下请求头，将 <API Key> 替换为用户提供的完整密钥：

text
Authorization: ApiKey <API Key>
X-Mht-Source-Key: cloud

Authorization 的认证方案是 ApiKey。密钥不是账号密码、密钥描述或密钥 ID；不要使用 Bearer，也不要将密钥放入 URL。

配置时，使用当前 Agent 客户端支持的 MCP 配置方式，并保留其他服务。密钥保存到该客户端支持的凭据环境变量或本机私有配置，不写入项目共享文件；回复中隐藏密钥。仅能读取本文、不能修改本机配置的客户端，应明确提供手工配置步骤。

验证时先完成 MCP 初始化并读取 tools 列表，再调用 get_context 检查账号和来源，调用 list_devices 查询设备。HTTP 状态正常或 tools 可见，并不单独证明账号权限已经验证。不要通过修改数据验证连接。

本地素材直传流程 ​

可获取 upload_media_resource_workflow prompt，按以下流程执行：

步骤MCP 工具 / 本地操作要点
1. 初始化init_media_resource_upload本地读取文件名、实际字节数和完整 MIME 类型；默认 uploadMode=direct，取得临时上传地址、全部请求头和 upload 对象
2. 直传文件本地 curl、Windows curl.exe 或脚本将原始文件字节 PUT 到返回地址，保留全部返回请求头；不要额外附加 MCP API Key
3. 完成入库complete_media_resource_upload将 upload 对象原样传回；只有返回 status=uploaded 和 mediaResourceId 才确认成功
4. 失败或取消abort_media_resource_upload传输失败或明确取消时清理；完成请求超时、结果不明确时，先用 list_media_resources 核对，不要立即重传或取消

大文件可使用 uploadMode=multipart：按初始化返回的 partSize 切分文件，通过 get_media_resource_upload_part 取得各分片地址，上传后保留原始 ETag，按分片顺序完成入库。

全流程使用同一来源和账号，现有权限、存储容量和文件大小限制仍然生效。临时上传地址、请求头和会话标识不写入日志或用户摘要。

常见问题 ​

遇到的情况如何处理
找不到“API 密钥”入口确认已登录联网账户；检查头像菜单或账户设置，必要时更新管理端或刷新网页
关闭生成窗口后找不到完整密钥完整值只显示一次，请重新生成，并停用不用的旧密钥
Agent 提示认证失败检查密钥是否启用、过期或被删除；确认复制了完整值，并使用 Authorization: ApiKey <密钥>
Agent 无法连接服务检查 MCP 地址、网络及 9394 端口是否可达；重新连接或重启客户端，不要把文档地址或管理端地址当成 MCP 地址
能连接，但某个操作提示无权限API Key 继承账号权限；确认登录账号、数据归属和目标操作权限
上传本地文件失败确认 Agent 能访问文件且具备脚本执行能力；请 Agent 检查上传阶段和存储返回结果，不要反复创建重复素材

高级场景：内网服务 ​

仅管理内网服务数据时，可在管理端或显示端的“内网服务”页面开启 MCP，使用该页面显示的 MCP 地址，例如 http://192.168.1.10:9394/mcp。Agent 应能访问该 MCP 服务，MCP 服务也应能访问目标内网服务；公开云端 MCP 无法直接访问客户内网地址。

使用对应内网服务账号创建的 API Key，并设置：

text
Authorization: ApiKey <内网服务 API Key>
X-Mht-Source-Key: lan
X-Mht-Lan-Host: http://192.168.1.10:9393

将示例 IP 替换为实际服务地址。除非相关进程在同一台机器上，否则不要使用 127.0.0.1。内网 LOCAL 存储的文件直接上传到内网服务，其他存储上传到所选对象存储。

内网来源调用授权码等云端专属能力时，可另外提供 X-Mht-Cloud-Authorization: ApiKey <联网账号 API Key>；普通内网设备、节目和素材查询无需额外提供联网账号密钥。

其他接入方式：STDIO ​

系统仍保留由 Agent 按需启动的 STDIO MCP，适合已有本地程序或特殊集成环境。常规云端接入和本地素材上传按本文的 HTTP 方式即可；无需另行下载 STDIO 程序或部署 Docker。