MCP 服务器 (AI 助手集成)

边缘盒子本身就是 MCP 服务器。 像 Claude 这样的 AI 助手会直接询问现场的盒子——有多少个 OPC 连接、这个标签的当前值是多少、采集是否积压。

不经过平台。即使盒子与平台断开连接，只要能连接到盒子，它就能回答。

项目	值
端点	`POST https://<엣지>/api/v1/mcp`
传输	Streamable HTTP，无状态
服务器名称	`plantpulse-edge` (版本会如实报告盒子的版本)
提供	6 种工具—全部只读
认证	与 `/api/` 相同的 API 密钥。* 没有 MCP 专用认证

连接方法

# Claude Code
claude mcp add --transport http plantpulse-edge "https://<엣지>/api/v1/mcp" \
  --header "X-API-Key: <edge.rest.api.key>"

// Claude Desktop — .mcp.json
{
  "mcpServers": {
    "plantpulse-edge": {
      "type": "http",
      "url": "https://<엣지>/api/v1/mcp",
      "headers": { "X-API-Key": "<edge.rest.api.key>" }
    }
  }
}

X-API-Key 也可以用 Authorization: Bearer <key> 代替。密钥与 REST API 相同(edge.rest.api.key)——请参阅 REST API。

🔴 使用 http:// 连接时，会返回 403 — 即使密钥正确也会被拒绝

edge.rest.api.https_only 的默认值是 true，因此外部客户端(X-API-Key·Bearer)调用必须使用 HTTPS。如果以明文传输，在检查密钥之前就会以 403 HTTPS_REQUIRED 断开连接。

如果在反向代理后面，X-Forwarded-Proto: https 也被认可。如果连接被拒绝，请先不要怀疑密钥，而应首先检查协议 — 如果是 401 而是 403，就是这种情况。

如果密钥为空，整个 /api/* 会返回 500

edge.rest.api.auth 默认是 true(fail-closed)，此时如果 edge.rest.api.key 为空，盒子会拒绝所有 /api/* 请求并返回 500 MISCONFIGURED。 这不是「没有配置就允许」，而是「没有配置就拒绝」——这是为了防止配置文件丢失的盒子无认证打开而有意设计的行为。

如果已在控制台浏览器中登录，则无需密钥即可

同域名的 /ui/* 界面调用的 /api/* 会通过已登录的会话。API 密钥是保护外部调用(REST 客户端 · Node-RED · MCP)的机制。

6 种工具 — 全部只读

工具	功能	必填参数
`list_opcs`	此盒子上配置的 OPC 连接列表	—
`get_opc`	按 id 查询一个 OPC 连接	`opcId`
`list_tags`	一个 OPC 连接的标签列表	`opcId`
`get_tag_value`	一个标签的当前值 — 不是缓存，而是从设备重新读取	`tagId`
`get_monitoring`	此盒子的采集管道健康状态	—
`get_transfer_status`	向平台进行 store-and-forward 传输的状态	—

工具不是新代码。 它们直接调用 AI 聊天所使用的那些服务(ConnectService · MonitoringQueryService)——这样可以避免同一问题两条路径给出不同答案的情况。

🔴 可以操作 PLC 的工具刻意没有提供

边缘的工具集中也有 start_opc · stop_opc · write_tag。但它们对 MCP 不开放。

在聊天路径中，这三个工具会经过人工审批界面(/ui/ai/approve)。MCP 客户端不会经过这个界面。而且 write_tag 会写入 PLC — 物理设备会移动。 没有审批的路径不应接触到那里。

将来如果确实需要写入工具，我们会先将审批机制迁移到 MCP 内部，然后再开放。先添加工具是绕过安全措施的最简单途径。产品中有防止此类情况的回归测试。

为什么是无状态的

因为这是适合现场盒子的形态。使用会话的传输需要服务器持有每个会话的状态，而现场线路断开和重连是常态，每次都需要识别客户端并重新连接。盒子重启后，所有会话都会立即消失。

无状态则独立处理每个请求 — 没有需要重连的，也没有需要丢失的，而且在堆内存 2GB 的设备上，会话表不会增长。

如何验证连接成功

检查 tools/list 是否返回 6 种工具。

工具列表可能看起来为«空»，但服务器看起来正常

即使工具扫描找不到任何东西，MCP 服务器也会正常启动 — 只是报告一个空的 tools/list。客户端无法将其与「这个边缘没有工具」区分开来。 连接断开的问题会被解读为产品事实。

因此，盒子会在日志中以 ERROR 级别明显记录此状态。如果列表为空，请在边缘日志中找到 MCP tool scan produced NO tools。

另请参阅

REST API (v1) · 平台 MCP 服务器 — 平台侧有 22 种工具，并涵盖资产、报警、本体

连接方法​

6 种工具 — 全部只读​

🔴 可以操作 PLC 的工具刻意没有提供​

为什么是无状态的​

如何验证连接成功​

另请参阅​