MCP Server

本文说明如何把信息发布系统的 MCP Server 配置到支持 MCP 的 AI Agent 中。

通过 MCP，Agent 可以在 API 密钥所属用户的权限范围内查询设备、节目、素材、分组和投放关系，并调用设备绑定、授权码查询、异常诊断和动态控制等自动化能力。MCP 不会绕过系统权限。

推荐从云端 HTTP MCP 开始

云端 MCP 服务已经运行，只需创建一个 API 密钥并配置 Agent，无需安装额外服务。熟悉后再按需使用 APP 内置 MCP、stdio MCP 或 Docker。

快速开始：云端 HTTP MCP

前置条件

一个有效的云端管理账号。
较新版本的管理端，能够在账号设置中管理 API 密钥。
Claude Code、Codex、Cursor 或其他支持 Streamable HTTP MCP 的 Agent。

第 1 步：创建 MCP 专用 API 密钥

登录管理端。
点击头像菜单中的“API 密钥”，也可以从账号设置进入。
新建密钥，描述建议填写 MCP 或具体 Agent 名称，并设置合理的有效期。
创建成功后立即保存完整密钥；完整值只显示一次，列表中无法再次查看。

建议为每个 Agent 创建独立密钥，便于单独禁用、删除和审计。

第 2 步：配置 Agent

Claude Code

bash

export CX_MCP_API_KEY='<你的云端API密钥>'
export CX_MCP_AUTHORIZATION="ApiKey $CX_MCP_API_KEY"

claude mcp add --transport http \
  cx-cloud http://127.0.0.1:9394/mcp \
  --header "Authorization: $CX_MCP_AUTHORIZATION" \
  --header "X-Mht-Source-Key: cloud"

Codex

启动 Codex 前设置包含完整认证方案的环境变量：

bash

export CX_MCP_AUTHORIZATION='ApiKey <你的云端API密钥>'

编辑 ~/.codex/config.toml：

toml

[mcp_servers.cx_cloud]
url = "http://127.0.0.1:9394/mcp"
http_headers = { "X-Mht-Source-Key" = "cloud" }
env_http_headers = { "Authorization" = "CX_MCP_AUTHORIZATION" }

env_http_headers 会从环境变量读取请求头值，密钥无需写入 config.toml。具体配置项可参考 OpenAI 官方 MCP 文档。

第 3 步：验证

bash

# Claude Code
claude mcp list
claude mcp get cx-cloud

# Codex
codex mcp list
codex mcp get cx_cloud

确认服务已连接并能看到 tools 后，可以尝试：

“列出我的所有设备。”
“查一下这台设备当前播放的节目。”
“这个节目投放到了哪些设备？”

Source 与 API 密钥

MCP 支持 Cloud 和 LAN 两种来源。API 密钥必须由对应来源的账号创建。

	Cloud	LAN
场景	联网、远程管理	内网或离线部署
主 API 密钥	云端账号创建	当前内网服务账号创建
前置服务	云端 MCP 已部署	管理端开启内网服务
授权码等云端专属 tools	主密钥直接可用	可选增加 Cloud API 密钥

Cloud HTTP 请求头

text

Authorization: ApiKey <cloud-key>
X-Mht-Source-Key: cloud

LAN HTTP 请求头

text

Authorization: ApiKey <lan-key>
X-Mht-Source-Key: lan
X-Mht-Lan-Host: http://127.0.0.1:9393

LAN source 调用授权码等云端专属 tools 时，再增加：

text

X-Mht-Cloud-Authorization: ApiKey <cloud-key>

这里的两个密钥用途不同：LAN API 密钥访问当前内网服务；Cloud API 密钥只访问云端专属能力。普通 LAN 设备和节目查询不需要 Cloud API 密钥。

APP 内置 HTTP MCP

在管理端或显示端 APP 的“内网服务”页面打开 MCP 服务。界面会显示类似地址：

text

http://192.168.1.10:9394/mcp

同一局域网内的 Agent 使用该地址连接。除非 Agent 与 APP 在同一台设备上，否则不要使用 127.0.0.1。

APP 内置 MCP 与独立 HTTP MCP 使用相同请求头：Cloud source 使用云端 API 密钥；LAN source 使用内网服务 API 密钥，并配置实际的 LAN host。

stdio MCP

cxmcp_stdio 由 Agent 按需启动，不需要常驻 HTTP MCP。正式使用建议通过环境变量传入原始密钥值。

Cloud

bash

export CX_MCP_API_KEY='<cloud-key>'
/path/to/cxmcp_stdio --source cloud

也可以指定自定义环境变量名：

bash

export MY_CX_API_KEY='<cloud-key>'
/path/to/cxmcp_stdio \
  --source cloud \
  --api-key-env MY_CX_API_KEY

LAN

bash

export CX_MCP_API_KEY='<lan-key>'
export CX_MCP_CLOUD_API_KEY='<cloud-key>' # 可选

/path/to/cxmcp_stdio \
  --source lan \
  --lan-host http://127.0.0.1:9393

支持的凭证参数只有：

--api-key、--api-key-env，默认环境变量为 CX_MCP_API_KEY。
--cloud-api-key、--cloud-api-key-env，默认环境变量为 CX_MCP_CLOUD_API_KEY。

命令行参数适合临时调试；长期配置优先使用环境变量，避免密钥出现在命令历史中。

Docker stdio MCP

Docker 版仍然是 stdio MCP，必须使用 docker run -i，不需要映射端口。

Cloud

bash

docker run -i --rm \
  -e CX_MCP_API_KEY='<cloud-key>' \
  <cxmcp-stdio-image> \
  --source cloud

LAN

bash

docker run -i --rm \
  --add-host=host.docker.internal:host-gateway \
  -e CX_MCP_API_KEY='<lan-key>' \
  -e CX_MCP_CLOUD_API_KEY='<cloud-key>' \
  <cxmcp-stdio-image> \
  --source lan \
  --lan-host http://host.docker.internal:9393

Docker Desktop 中容器访问宿主机服务应使用 host.docker.internal。Linux 如未提供该名称，需要保留上例中的 --add-host。

完整 Agent 配置

Claude Code：HTTP LAN

bash

export CX_MCP_LAN_AUTHORIZATION='ApiKey <lan-key>'
export CX_MCP_CLOUD_AUTHORIZATION='ApiKey <cloud-key>' # 可选

claude mcp add --transport http \
  cx-lan http://127.0.0.1:9394/mcp \
  --header "Authorization: $CX_MCP_LAN_AUTHORIZATION" \
  --header "X-Mht-Source-Key: lan" \
  --header "X-Mht-Lan-Host: http://127.0.0.1:9393" \
  --header "X-Mht-Cloud-Authorization: $CX_MCP_CLOUD_AUTHORIZATION"

不使用云端专属 tools 时，删除最后一个 header。

Claude Code：stdio

bash

# Cloud
claude mcp add cx-cloud-stdio \
  -e CX_MCP_API_KEY='<cloud-key>' \
  -- /path/to/cxmcp_stdio --source cloud

# LAN
claude mcp add cx-lan-stdio \
  -e CX_MCP_API_KEY='<lan-key>' \
  -e CX_MCP_CLOUD_API_KEY='<cloud-key>' \
  -- /path/to/cxmcp_stdio \
    --source lan \
    --lan-host http://127.0.0.1:9393

Codex：HTTP LAN

bash

export CX_MCP_LAN_AUTHORIZATION='ApiKey <lan-key>'
export CX_MCP_CLOUD_AUTHORIZATION='ApiKey <cloud-key>' # 可选

toml

[mcp_servers.cx_lan]
url = "http://127.0.0.1:9394/mcp"
http_headers = { "X-Mht-Source-Key" = "lan", "X-Mht-Lan-Host" = "http://127.0.0.1:9393" }
env_http_headers = { "Authorization" = "CX_MCP_LAN_AUTHORIZATION", "X-Mht-Cloud-Authorization" = "CX_MCP_CLOUD_AUTHORIZATION" }

不使用云端专属 tools 时，从 env_http_headers 删除 X-Mht-Cloud-Authorization。

Codex：stdio

toml

[mcp_servers.cx_cloud_stdio]
command = "/path/to/cxmcp_stdio"
args = ["--source", "cloud"]
env = { "CX_MCP_API_KEY" = "<cloud-key>" }

[mcp_servers.cx_lan_stdio]
command = "/path/to/cxmcp_stdio"
args = ["--source", "lan", "--lan-host", "http://127.0.0.1:9393"]
env = { "CX_MCP_API_KEY" = "<lan-key>", "CX_MCP_CLOUD_API_KEY" = "<cloud-key>" }

Cursor：HTTP Cloud

在 ~/.cursor/mcp.json 中配置：

json

{
  "mcpServers": {
    "cx-cloud": {
      "url": "http://127.0.0.1:9394/mcp",
      "headers": {
        "Authorization": "ApiKey <cloud-key>",
        "X-Mht-Source-Key": "cloud"
      }
    }
  }
}

如果 Agent 支持从环境变量读取 header，应优先使用环境变量，避免密钥进入配置文件。

常见问题

连接失败或 tools 调用失败

依次检查：

API 密钥是否仍处于启用状态。
API 密钥是否已经到期或被删除。
HTTP header 是否严格使用 ApiKey <key>。
Cloud/LAN 密钥是否与当前 source 匹配。
密钥所属用户是否有权执行目标操作。
LAN 是否配置 X-Mht-Source-Key: lan 和正确的 X-Mht-Lan-Host。
LAN 调用云端专属 tools 时，是否额外配置可用的 Cloud API 密钥。

API 密钥失效后不会自动恢复。请创建或启用可用密钥，并更新 Agent 配置。

tools 列表为空

确认 MCP URL 和端口正确。
确认完整认证 header 已传给 MCP 客户端。
在 Agent 中重新连接服务，例如 Claude Code 中重新运行 /mcp。
检查 source 和密钥权限。

HTTP MCP 端口被占用

本地运行时可修改端口：

bash

cxmcp_http --port=9395

同时修改 Agent 配置中的 URL。云端 HTTP MCP 不受此影响。

同时使用 LAN 和 Cloud

建议配置两个独立服务，例如 cx_cloud 和 cx_lan。它们可以指向同一 MCP URL，但必须使用各自来源的 API 密钥和 source header。

安全注意

为 MCP 创建专用 API 密钥，不与其他集成共用。
设置符合使用周期的有效期，并定期轮换。
完整密钥只显示一次，创建后立即保存到安全位置。
优先使用环境变量或本机私有配置，禁止提交到代码仓库。
不再使用时立即禁用或删除密钥。
HTTP MCP 默认绑定 127.0.0.1；只有在明确配置网络访问控制后才对外监听。

MCP Server ​

快速开始：云端 HTTP MCP ​

前置条件 ​

第 1 步：创建 MCP 专用 API 密钥 ​

第 2 步：配置 Agent ​

Claude Code ​

Codex ​

第 3 步：验证 ​

Source 与 API 密钥 ​

Cloud HTTP 请求头 ​

LAN HTTP 请求头 ​

APP 内置 HTTP MCP ​

stdio MCP ​

Cloud ​

LAN ​

Docker stdio MCP ​

Cloud ​

LAN ​

完整 Agent 配置 ​

Claude Code：HTTP LAN ​

Claude Code：stdio ​

Codex：HTTP LAN ​

Codex：stdio ​

Cursor：HTTP Cloud ​

常见问题 ​

连接失败或 tools 调用失败 ​

tools 列表为空 ​

HTTP MCP 端口被占用 ​

同时使用 LAN 和 Cloud ​

安全注意 ​

MCP Server

快速开始：云端 HTTP MCP

前置条件

第 1 步：创建 MCP 专用 API 密钥

第 2 步：配置 Agent

Claude Code

Codex

第 3 步：验证

Source 与 API 密钥

Cloud HTTP 请求头

LAN HTTP 请求头

APP 内置 HTTP MCP

stdio MCP

Cloud

LAN

Docker stdio MCP

Cloud

LAN

完整 Agent 配置

Claude Code：HTTP LAN

Claude Code：stdio

Codex：HTTP LAN

Codex：stdio

Cursor：HTTP Cloud

常见问题

连接失败或 tools 调用失败

tools 列表为空

HTTP MCP 端口被占用

同时使用 LAN 和 Cloud

安全注意