MCP Server

本文面向外部用户，说明如何把 CX 的 MCP Server 配置到 Claude Code、Codex 等 Agent。

能做什么

当前 MCP Server 提供以下 tools：

get_context：查看当前连接的 source、用户、tenant、customer 信息。
list_devices：列出当前用户可见设备。
list_programs：列出当前用户可见节目。
get_device_status：查询单个当前用户可见设备的在线状态和版本属性。
get_device_detail：查询单个当前用户可见设备的详情和最新属性。
get_program_detail：查询单个当前用户可见节目的详细内容。
list_assets：列出当前用户可见的资产和分组。
get_entity_attributes：按明确指定的 keys 查询设备、节目或资产属性。
list_program_targets：查询节目当前投放到哪些可见设备或分组。
list_device_programs：查询某个可见设备当前关联的节目。
bind_device_by_ddc：使用设备动态码绑定或创建设备，可传入已选择的可用设备授权码 id。
describe_device_binding_semantics：说明通过动态码绑定设备时 Cloud/LAN 的授权码使用规则。
describe_activation_semantics：说明授权码类型、设备授权码和联网账户 token 要求。
list_activation_codes：查询联网账户可见授权码，可用 status: "usable" 筛选可用设备授权码。
list_usable_device_auth_codes：查询当前可用于设备绑定的可用设备授权码。
get_activation_code：查询单个授权码详情。
activate_code：激活普通授权码。

MCP Server 会使用你的登录 token 访问数据，因此不同用户只能看到自己有权限访问的内容。

选择哪种连接方式

CX 提供三种 MCP 入口：

APP 内置 HTTP MCP：适合直接连接已经打开的管理端/显示端 APP，地址是 http://<设备局域网IP>:9394/mcp。
独立 HTTP MCP：适合连接已经常驻运行的 cxmcp_http，默认地址是 http://127.0.0.1:9394/mcp。
stdio MCP：适合 Claude Code、Codex 等本机 Agent 直接启动 cxmcp_stdio 可执行文件。

如果 Agent 和 CX APP 在同一局域网，优先使用 APP 内置 HTTP MCP；如果希望在服务器上常驻运行，使用独立 HTTP MCP；如果只想让 Agent 按需启动 MCP，使用 stdio MCP。

启动 cxserver

启动本地 HTTP Server：

bash

./run.sh

cxserver 只负责本地 HTTP Server，不会启动 MCP。

在 APP 中启动 HTTP MCP

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

text

http://192.168.1.10:9394/mcp

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

启动 HTTP MCP

bash

cxmcp_http

自定义 HTTP MCP 地址：

bash

cxmcp_http --host=127.0.0.1 --port=9394 --path=/mcp

Token 和 Source

每个 MCP 连接都需要一个有效的登录 JWT。

HTTP MCP 使用请求头：

text

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

LAN 本地服务使用：

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>

stdio MCP 使用环境变量和命令参数。示例使用 CX_MCP_* 变量名，因此需要显式传入 --token-env 和 --cloud-token-env：

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，并显式传给 CLI：

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

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

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）中，容器访问宿主机的 cxserver 应使用 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"

检查：

bash

claude mcp list
claude mcp get cx-lan

进入 Claude Code 后可运行：

text

/mcp

确认 cx-lan 或 cx-cloud 已连接并能看到 tools。

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：

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>" }

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

移除：

bash

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：

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>

如果 Agent 支持 stdio MCP：

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。

配置参数变化后不生效

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

LAN 和 Cloud 同时使用

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

cx_cloud
cx_lan

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

安全注意

不要把 JWT 写入仓库。
本地测试优先使用环境变量或本机私有配置文件。
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 ​

能做什么 ​

选择哪种连接方式 ​

启动 cxserver ​

在 APP 中启动 HTTP MCP ​

启动 HTTP MCP ​

Token 和 Source ​

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 ​

常见问题 ​

连接失败或 tools 调用失败 ​

配置参数变化后不生效 ​

LAN 和 Cloud 同时使用 ​

安全注意 ​

MCP Server

能做什么

选择哪种连接方式

启动 cxserver

在 APP 中启动 HTTP MCP

启动 HTTP MCP

Token 和 Source

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

常见问题

连接失败或 tools 调用失败

配置参数变化后不生效

LAN 和 Cloud 同时使用

安全注意