MCP Server

本文面向外部用户，说明如何把信息发布系统的 MCP Server 配置到支持 MCP 的 AI Agent 中。

通过 MCP，Agent 可以在用户授权范围内读取信息发布系统的数据，并调用系统提供的自动化能力，用于设备巡检、节目查询、投放核对、设备绑定、异常诊断和动态控制等工作流。它的目标不是替代后台管理界面，而是让 Agent 能够基于自然语言和自动化计划，完成重复性查询、批量核对和远程控制辅助。

推荐从云端HTTP MCP服务开始

云端HTTP MCP服务是最简单的接入方式——云端MCP服务器已开启，只需在 Agent 中配置即可，无需安装或运行任何额外服务。source 固定为联网（cloud）模式。熟悉后再根据需要尝试 APP 内置 MCP、stdio MCP 或 Docker 部署等高级配置。

能做什么

MCP Server 面向信息发布系统的自动化控制场景。Agent 连接后，可以在当前登录用户权限范围内：

查看当前连接上下文，包括数据来源、用户、租户和客户范围。
查询可见设备、节目、素材、分组和投放关系。
读取设备状态、节目详情、实体属性和设备当前关联节目。
辅助完成设备绑定、授权码查询和激活等管理流程。
结合 Agent 的计划和对话能力，执行批量巡检、状态核对、远程投放检查和动态控制建议等自动化工作流。

MCP Server 不会绕过系统权限。所有请求都会使用当前配置的登录 token 和 source 上下文执行，因此不同用户只能访问自己有权限的数据和操作。

快速开始：云端HTTP MCP服务（推荐）

云端MCP服务器已开启，你只需获取 Token 并在 Agent 中配置，无需安装或运行任何额外服务。云端HTTP MCP服务的 source 固定为联网（cloud）模式。整个过程分两步：获取 Token → 配置 Agent。

前置条件

拥有有效的管理端账号。
已安装 Claude Code 或 Codex 等 MCP 兼容 Agent。

兼容性

MCP Server 从管理端较新版本开始支持。如果你的管理端版本较旧，请先升级。Agent 侧建议使用 Claude Code 或 Codex 的最新版本。

第 1 步：获取 JWT Token

登录管理端（Web 或客户端），点击用户头像，选择「复制Token」。

这个 Token 就是 MCP 连接时使用的身份凭证，请妥善保管，不要分享或提交到代码仓库。

第 2 步：在 Agent 中配置

Claude Code

bash

export CX_MCP_TOKEN='<你的JWT>'

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

Codex

编辑 ~/.codex/config.toml：

toml

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

启动 Codex 前设置环境变量：

bash

export CX_MCP_TOKEN='<你的JWT>'
codex

Codex 版本说明

bearer_token_env_var 字段在较新版本的 Codex 中支持。如果你的 Codex 版本不支持该字段，请改用 http_headers 直接传 Authorization: Bearer <jwt>，或升级 Codex 到最新版本。

验证连接

在 Agent 中检查 MCP 连接状态：

bash

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

# 进入 Claude Code 后运行
/mcp

bash

# Codex
codex mcp list
codex mcp get cx_cloud

确认 cx-cloud 已连接并能看到 tools，说明配置成功。接下来你可以在对话中试试：

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

初级教程到此结束

上面的「快速开始」已经能覆盖大多数用户的需求。以下内容涉及 Token 原理、LAN 内网模式、stdio、Docker 等高级配置，适合有特定场景需求的用户按需阅读。

Token 和 Source

上文的快速开始使用了 Cloud source（联网模式），这也是大多数用户的首选。如果你需要在内网/离线环境下使用 MCP，需要了解 LAN source。

两种 Source

	Cloud	LAN
适用场景	设备能联网，远程管理	设备不能上外网，内网/离线环境
Token 来源	管理端登录后的联网账户 JWT	管理端本机服务的 LAN JWT
前置服务	无（直连云端）	在管理端开启本机服务
授权码/MHActivation tools	直接可用	需额外提供联网账户 JWT

Cloud Source 的 HTTP Header

text

Authorization: Bearer <jwt>
X-Mht-Source-Key: cloud

LAN Source 的 HTTP Header

text

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

部分云端功能（例如授权码/MHActivation tools）必须使用联网账户。LAN source 下如需使用这类功能，需要额外提供联网账户 JWT：

text

X-Mht-Cloud-Authorization: Bearer <cloud-jwt>

建议用环境变量传 token，不要把 JWT 写入仓库或共享配置。

高级配置

以下方式适合在熟悉云端HTTP MCP服务后，根据场景需要进一步选用。例如：需要在内网/离线环境使用 LAN source、让 Agent 按需启动 MCP、或通过 Docker 部署。

APP 内置 HTTP MCP

平台支持

APP 内置 MCP 支持管理端和显示端的 Android、Windows、Linux 版本（需较新版本）。如果找不到"本机服务"界面，请先升级 APP。

在管理端或显示端 APP 的"本机服务"界面打开 MCP 服务开关。开启后，界面会显示类似：

text

http://192.168.1.10:9394/mcp

同一局域网内的 Agent 使用这个地址连接。不要把 APP 内置 MCP 配置为 127.0.0.1，除非 Agent 和 APP 运行在同一台设备上。

stdio MCP

stdio MCP 适合让 Claude Code、Codex 等 Agent 直接启动 cxmcp_stdio 可执行文件，不需要单独常驻 HTTP 服务。cxmcp_stdio 同样包含在管理端安装包中。

Cloud 模式：

bash

CX_MCP_TOKEN='<jwt>' /path/to/cxmcp_stdio \
  --source cloud \
  --token-env CX_MCP_TOKEN

LAN 模式：

bash

CX_MCP_TOKEN_LAN='<lan-jwt>' /path/to/cxmcp_stdio \
  --source lan \
  --token-env CX_MCP_TOKEN_LAN \
  --lan-host http://127.0.0.1:9393

LAN source 如需使用授权码/MHActivation tools，需要额外提供联网账户 token：

bash

CX_MCP_TOKEN_LAN='<lan-jwt>' CX_MCP_CLOUD_TOKEN='<cloud-jwt>' /path/to/cxmcp_stdio \
  --source lan \
  --token-env CX_MCP_TOKEN_LAN \
  --cloud-token-env CX_MCP_CLOUD_TOKEN \
  --lan-host http://127.0.0.1:9393

Docker stdio MCP

Docker 版 cxmcp_stdio 可以替代本机可执行文件安装。它仍然是 stdio MCP，运行时必须使用 docker run -i，不要使用 -d，也不需要映射端口。请将 <cxmcp-stdio-image> 替换为实际 OEM 或部署环境提供的镜像名。

Cloud：

bash

docker run -i --rm \
  -e CX_MCP_TOKEN='<jwt>' \
  <cxmcp-stdio-image> \
  --source cloud \
  --token-env CX_MCP_TOKEN

LAN：

bash

export CX_MCP_LAN_HOST='http://host.docker.internal:9393'

docker run -i --rm \
  -e CX_MCP_TOKEN_LAN='<lan-jwt>' \
  -e CX_MCP_CLOUD_TOKEN='<cloud-jwt>' \
  <cxmcp-stdio-image> \
  --source lan \
  --token-env CX_MCP_TOKEN_LAN \
  --cloud-token-env CX_MCP_CLOUD_TOKEN \
  --lan-host "$CX_MCP_LAN_HOST"

在 Docker Desktop（macOS/Windows）中，容器访问宿主机的本地服务应使用 host.docker.internal，不要使用 127.0.0.1。Linux Docker 如果没有 host.docker.internal，运行时加：

bash

--add-host=host.docker.internal:host-gateway

Claude Code 完整配置

如果 token、source 或 LAN host 变化，建议先移除旧配置，再重新添加，避免旧 header 或环境变量残留：

bash

claude mcp remove cx-cloud -s local
claude mcp remove cx-lan -s local
claude mcp remove cx-cloud-stdio -s local
claude mcp remove cx-lan-stdio -s local

HTTP Cloud

bash

export CX_MCP_TOKEN='<jwt>'

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

HTTP LAN

bash

export CX_MCP_TOKEN_LAN='<lan-jwt>'
export CX_MCP_CLOUD_TOKEN='<cloud-jwt>'
export CX_MCP_LAN_HOST='http://127.0.0.1:9393'

claude mcp add --transport http \
  cx-lan http://127.0.0.1:9394/mcp \
  --header "Authorization: Bearer $CX_MCP_TOKEN_LAN" \
  --header "X-Mht-Source-Key: lan" \
  --header "X-Mht-Lan-Host: $CX_MCP_LAN_HOST" \
  --header "X-Mht-Cloud-Authorization: Bearer $CX_MCP_CLOUD_TOKEN"

X-Mht-Cloud-Authorization 只在 LAN source 需要访问联网账户功能时使用；普通 LAN 设备/节目查询可以不配置。

stdio Cloud

bash

claude mcp add cx-cloud-stdio \
  -e CX_MCP_TOKEN='<jwt>' \
  -- /path/to/cxmcp_stdio --source cloud --token-env CX_MCP_TOKEN

stdio LAN

bash

claude mcp add cx-lan-stdio \
  -e CX_MCP_TOKEN_LAN='<lan-jwt>' \
  -e CX_MCP_CLOUD_TOKEN='<cloud-jwt>' \
  -- /path/to/cxmcp_stdio \
    --source lan \
    --token-env CX_MCP_TOKEN_LAN \
    --cloud-token-env CX_MCP_CLOUD_TOKEN \
    --lan-host http://127.0.0.1:9393

也可以把 LAN host 放到环境变量：

bash

export CX_MCP_LAN_HOST='http://127.0.0.1:9393'

claude mcp add cx-lan-stdio \
  -e CX_MCP_TOKEN_LAN='<lan-jwt>' \
  -e CX_MCP_CLOUD_TOKEN='<cloud-jwt>' \
  -- /path/to/cxmcp_stdio \
    --source lan \
    --token-env CX_MCP_TOKEN_LAN \
    --cloud-token-env CX_MCP_CLOUD_TOKEN \
    --lan-host "$CX_MCP_LAN_HOST"

Codex 完整配置

Codex 使用 ~/.codex/config.toml 配置 MCP Server。HTTP MCP 可配置 url，stdio MCP 可配置 command/args/env。

如果 source 或 LAN host 变化，建议先从 ~/.codex/config.toml 删除对应 [mcp_servers.<name>] 配置块，再重新写入。

HTTP Cloud

toml

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

启动 Codex 前设置环境变量：

bash

export CX_MCP_TOKEN='<jwt>'
codex

HTTP LAN

toml

[mcp_servers.cx_lan]
url = "http://127.0.0.1:9394/mcp"
bearer_token_env_var = "CX_MCP_TOKEN_LAN"
http_headers = { "X-Mht-Source-Key" = "lan", "X-Mht-Lan-Host" = "http://127.0.0.1:9393", "X-Mht-Cloud-Authorization" = "Bearer <cloud-jwt>" }

如果不想把联网账户 JWT 写入 config.toml，可先不配置 X-Mht-Cloud-Authorization，或使用 stdio MCP 通过 env 传入 CX_MCP_CLOUD_TOKEN。

stdio Cloud

toml

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

stdio LAN

toml

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

如需切换 LAN host，直接修改 --lan-host 的值。注意 Codex 的 args 不会做 shell 变量展开，因此不要在这里写 $CX_MCP_LAN_HOST，要写实际地址。

Docker stdio Cloud

toml

[mcp_servers.cx_cloud_stdio_docker]
command = "docker"
args = [
  "run", "-i", "--rm",
  "-e", "CX_MCP_TOKEN",
  "<cxmcp-stdio-image>",
  "--source", "cloud",
  "--token-env", "CX_MCP_TOKEN"
]
env = { "CX_MCP_TOKEN" = "<jwt>" }

Docker stdio LAN

toml

[mcp_servers.cx_lan_stdio_docker]
command = "docker"
args = [
  "run", "-i", "--rm",
  "--add-host=host.docker.internal:host-gateway",
  "-e", "CX_MCP_TOKEN_LAN",
  "-e", "CX_MCP_CLOUD_TOKEN",
  "<cxmcp-stdio-image>",
  "--source", "lan",
  "--token-env", "CX_MCP_TOKEN_LAN",
  "--cloud-token-env", "CX_MCP_CLOUD_TOKEN",
  "--lan-host", "http://host.docker.internal:9393"
]
env = { "CX_MCP_TOKEN_LAN" = "<lan-jwt>", "CX_MCP_CLOUD_TOKEN" = "<cloud-jwt>" }

检查和移除：

bash

codex mcp list
codex mcp get cx_lan

# 移除
codex mcp remove cx_cloud
codex mcp remove cx_lan
codex mcp remove cx_cloud_stdio
codex mcp remove cx_lan_stdio

如果当前 Codex 版本没有 mcp remove 命令，可直接编辑 ~/.codex/config.toml，删除对应配置块。

其他 Agent

如果你的 Agent 不在上述列表中，可以参考以下通用配置参数。

支持 Streamable HTTP MCP 的 Agent

通用 HTTP 参数：

URL：http://127.0.0.1:9394/mcp
Header：Authorization: Bearer <jwt>
Cloud Header：X-Mht-Source-Key: cloud
LAN Header：X-Mht-Source-Key: lan
LAN Header：X-Mht-Lan-Host: http://127.0.0.1:9393
LAN 可选 Cloud Header：X-Mht-Cloud-Authorization: Bearer <cloud-jwt>

Cursor 示例（在 ~/.cursor/mcp.json 中配置）：

json

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

支持 stdio MCP 的 Agent

通用 stdio 参数：

Command：/path/to/cxmcp_stdio
Cloud args：--source cloud --token-env CX_MCP_TOKEN
LAN args：--source lan --token-env CX_MCP_TOKEN_LAN --cloud-token-env CX_MCP_CLOUD_TOKEN --lan-host http://127.0.0.1:9393
Cloud Env：CX_MCP_TOKEN=<jwt>
LAN Env：CX_MCP_TOKEN_LAN=<lan-jwt>
LAN 可选 Env：CX_MCP_CLOUD_TOKEN=<cloud-jwt>
LAN host 可先放在你自己的环境变量中，但启动参数仍需显式传入：--lan-host "$CX_MCP_LAN_HOST"
Docker Command：docker
Docker args：run -i --rm -e CX_MCP_TOKEN <cxmcp-stdio-image> --source cloud --token-env CX_MCP_TOKEN

常见问题

连接失败或 tools 调用失败

检查：

token 是否过期。
HTTP 模式是否使用 Authorization: Bearer <jwt> 格式。
token 是否属于当前 source。
LAN 模式是否配置了 X-Mht-Source-Key: lan 和 X-Mht-Lan-Host。
stdio LAN 是否配置了 --lan-host，或在 shell 示例中通过 --lan-host "$CX_MCP_LAN_HOST" 显式传入。
LAN source 调用授权码/MHActivation tools 时，是否额外配置了联网账户 token：HTTP 用 X-Mht-Cloud-Authorization，stdio 用 CX_MCP_CLOUD_TOKEN。

tools 列表为空

确认 Agent 配置的 MCP 服务地址正确。
在 Agent 中重新连接 MCP Server（如 Claude Code 中重新运行 /mcp）。
检查 token 是否有效：过期或无效的 token 可能导致 tools 列表为空但不报错。

token 过期

当前版本不支持 refresh token，token 过期后需要重新获取 JWT 并更新 Agent 配置。常见表现：

之前能用的 tools 突然返回权限错误或认证失败。
Agent 报告 MCP Server 连接断开。

重新获取 Token 后，更新环境变量或 Agent 配置中的 JWT 值即可。

HTTP MCP 端口被占用

如果你在本地运行 MCP 服务且 9394 端口被其他程序占用，可以自定义端口：

bash

cxmcp_http --port=9395

同时在 Agent 配置中把 URL 的端口改为对应值。使用云端HTTP MCP服务则不受此影响。

配置参数变化后不生效

先移除旧 MCP Server，再重新配置。尤其是 source、LAN host、command path 变化时，不建议直接覆盖。

LAN 和 Cloud 同时使用

建议配置成两个 MCP server，例如：

cx_cloud
cx_lan

它们可以使用同一个 HTTP MCP URL，但需要不同 token 和 source 配置。

安全注意

不要把 JWT 写入仓库。建议使用 .env 文件或环境变量管理，并将 .env 加入 .gitignore。
本地测试优先使用环境变量或本机私有配置文件。
HTTP MCP 默认绑定 127.0.0.1，不要随意暴露到公网。
stdio 模式推荐用 CX_MCP_TOKEN 环境变量传 token；--token 只建议临时调试使用。
LAN source 的 CX_MCP_CLOUD_TOKEN 是联网账户 JWT，同样不要写入仓库或共享配置。
当前版本不支持 refresh token，token 过期后需要重新提供新的 JWT。

MCP Server ​

能做什么 ​

快速开始：云端HTTP MCP服务（推荐） ​

前置条件 ​

第 1 步：获取 JWT Token ​

第 2 步：在 Agent 中配置 ​

Claude Code ​

Codex ​

验证连接 ​

Token 和 Source ​

两种 Source ​

Cloud Source 的 HTTP Header ​

LAN Source 的 HTTP Header ​

高级配置 ​

APP 内置 HTTP MCP ​

stdio MCP ​

Docker stdio MCP ​

Claude Code 完整配置 ​

HTTP Cloud ​

HTTP LAN ​

stdio Cloud ​

stdio LAN ​

Codex 完整配置 ​

HTTP Cloud ​

HTTP LAN ​

stdio Cloud ​

stdio LAN ​

Docker stdio Cloud ​

Docker stdio LAN ​

其他 Agent ​

支持 Streamable HTTP MCP 的 Agent ​

支持 stdio MCP 的 Agent ​

常见问题 ​

连接失败或 tools 调用失败 ​

tools 列表为空 ​

token 过期 ​

HTTP MCP 端口被占用 ​

配置参数变化后不生效 ​

LAN 和 Cloud 同时使用 ​

安全注意 ​

MCP Server

能做什么

快速开始：云端HTTP MCP服务（推荐）

前置条件

第 1 步：获取 JWT Token

第 2 步：在 Agent 中配置

Claude Code

Codex

验证连接

Token 和 Source

两种 Source

Cloud Source 的 HTTP Header

LAN Source 的 HTTP Header

高级配置

APP 内置 HTTP MCP

stdio MCP

Docker stdio MCP

Claude Code 完整配置

HTTP Cloud

HTTP LAN

stdio Cloud

stdio LAN

Codex 完整配置

HTTP Cloud

HTTP LAN

stdio Cloud

stdio LAN

Docker stdio Cloud

Docker stdio LAN

其他 Agent

支持 Streamable HTTP MCP 的 Agent

支持 stdio MCP 的 Agent

常见问题

连接失败或 tools 调用失败

tools 列表为空

token 过期

HTTP MCP 端口被占用

配置参数变化后不生效

LAN 和 Cloud 同时使用

安全注意