九、MCP 服务

网关内置 MCP（Model Context Protocol）服务端，将机台数据、数据分析与网关状态以「工具（Tool）」的形式提供给 AI 客户端（Claude Code、Claude Desktop、MCP Inspector 等支持 MCP 的应用与智能体），无需自行编写 HTTP 请求即可用自然语言查询机台。

MCP 工具在网关内部走与 HTTP 接口完全相同的处理流程。直通类工具（get_machine、read_tool_life、list_programs、read_task_data）返回的内容与对应 HTTP 接口完全一致；组合类工具（get_fleet_status、read_machine、analyze、query_history、get_system_info 等）一次调用多个接口并按 9.5. 返回结果与错误的说明合并或包装。字段含义参见五、HTTP 通讯各章节。

9.1. 基本说明

MCP 服务端地址为 /mcp，与 HTTP 接口使用同一端口：

http://{网关 IP}/mcp

注意

MCP 服务默认关闭，关闭时 /mcp 返回 HTTP 404。在3.6.8. MCP 设置中打开开关并保存即可启用，立即生效，无需重启网关或服务。

传输方式为 MCP 标准的 Streamable HTTP：客户端以 POST 发送 JSON-RPC 报文，请求头需带 Content-Type: application/json 与 Accept: application/json, text/event-stream。服务端为无状态模式，每次工具调用都是独立的一次 HTTP 请求。

当前提供 13 个只读工具，覆盖机台配置、实时状态、缓存快照、数据分析与网关系统信息，详见 9.4. 工具列表。所有涉及写入、机台控制、文件传输的接口均不提供 MCP 工具，只能通过 HTTP 接口调用。

面向智能体的设计：

• initialize 响应携带服务端使用说明（instructions）：推荐的调用顺序、时间参数写法、机台状态取值含义、常见错误码及处理建议、文档地址。
• 全部工具均标注为只读、幂等（readOnlyHint、idempotentHint），支持该标注的客户端可免确认调用。
• 所有时间参数接受多种写法（见 9.4. 工具列表），结果中回显按网关时区解析后的时间窗口。
• 错误消息附带处理提示，组合类工具按分项报告错误而不整体失败。

注

云平台（Hub）同样提供 MCP 服务端，地址为 https://{云平台地址}/mcp，工具列表与网关一致，调用时由云平台转发至指定网关执行，鉴权方式见 9.2.2. 云平台鉴权。

9.2. 鉴权

9.2.1. 网关鉴权

MCP 服务端的鉴权方式与 HTTP 接口一致，详见 5.3. 鉴权方式。请求头中带 Authorization: Bearer <token>，token 可以是 5.3.1. JWT 方式获取的令牌，也可以是 5.3.2. 密钥方式生成的密钥（管理员在3.12.1.3.2. 用户安全设置中为用户生成）。未提供或提供无效凭证时，返回 HTTP 401。

注意

JWT 令牌有效期为 24 小时，过期后 MCP 客户端会持续调用失败。MCP 客户端配置通常长期保存，建议使用永久有效的密钥。

其余访问控制同样生效：

• IP 白名单：在3.6.6. HTTP 设置中启用后，/mcp 请求的来源 IP 必须在白名单内，规则与 /api 相同，详见 5.3.3. IP 白名单。
• 用户授权 API：启用安全控制后，管理员用户可调用全部工具；非管理员用户只能调用其授权 API 列表覆盖到的接口（授权规则按工具背后实际调用的接口地址逐一匹配，与 HTTP 请求使用同一套配置）。组合类工具中未授权的分项在结果的 errors 中以 Forbidden: ... 报告，其余分项正常返回；单接口工具无权限时该次调用返回错误。
• 关闭安全控制后，可跳过用户鉴权直接调用工具（IP 白名单仍然生效）。

9.2.2. 云平台鉴权

调用云平台的 MCP 服务端时，请求头中带 accessToken: <网关令牌>，与云平台的 HTTP 代理使用同一套规则：该令牌既是鉴权凭证，也用于指定工具在哪个网关上执行。网关令牌即3.6.1. 云平台配置中填写的网关令牌，接口见 5.9.6.1. cloud-settings 获取云平台设置。

令牌缺失或未注册时，工具调用返回 Unauthorized: missing or unknown accessToken header.；令牌有效但对应网关当前未连接云平台时，返回 GATEWAY_SERVICE_UNAVAILABLE。

9.3. 客户端配置

以 Claude Code 为例，添加网关 MCP 服务端：

claude mcp add --transport http bivrost-gateway http://192.168.100.1/mcp --header "Authorization: Bearer <密钥>"

添加云平台 MCP 服务端：

claude mcp add --transport http bivrost-hub https://cloud.example.com/mcp --header "accessToken: <网关令牌>"

其它 MCP 客户端一般使用如下形式的 JSON 配置：

{
  "mcpServers": {
    "bivrost-gateway": {
      "type": "http",
      "url": "http://192.168.100.1/mcp",
      "headers": {
        "Authorization": "Bearer <密钥>"
      }
    }
  }
}

如需直接验证服务端是否可用，可用 JSON-RPC 请求列出全部工具：

curl -X POST http://192.168.100.1/mcp \
  -H "Authorization: Bearer <密钥>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

9.4. 工具列表

以下参数中标注「可选」的可以省略，省略时使用默认值。machineID 与 groupID 的含义见 4.1.1. 基本说明，可先用 list_machines、list_groups 获取。

时间参数（start、end）接受以下写法，按网关时区解析：Unix 时间戳（秒，13 位按毫秒处理）；带时区的 ISO-8601（2026-09-17T08:00:00+08:00）；不带时区的 ISO-8601 或日期（2026-09-17T08:00、2026-09-17，按网关本地时间）；相对时间（-30m、-24h、-7d、-2w）；关键字 now、today、yesterday（后两者为当天/前一天 0 点）。end 省略时为当前时间。

推荐调用顺序：list_machines → get_fleet_status（全厂概览）→ read_machine / analyze / query_history（单机细节）。

9.4.1. 配置查询

工具	说明	参数	对应接口
list_machines	列出全部机台的标识信息：machineID、name、system、model、machineType、ip、port、isActive	无	machines
list_groups	列出全部机组：groupID、name、isActive、成员 machineIDs	无	groups
get_machine	获取单个机台的完整配置（不含口令字段）	machineID	machine

9.4.2. 机台状态

工具	说明	参数	对应接口
get_fleet_status	一次返回全部机台（或某机组成员）的最新缓存状态与连接健康度，不访问机床。每台机台给出 connection（errorCode 为 0 表示通讯正常）、status（cncStatus、adjustedStatus、alarmStatus、alarmLevel、mode、programStatus、time）与归类 state（running / idle / alarm / setup / offline / noData / inactive），并汇总 summary 计数。连接中断时 state 为 offline，缓存状态标记 statusStale。需开启机台状态任务，未开启时 state 为 noData	groupID（可选）	machines、group、batchReadTaskData、batchReadErrors
read_task_data	读取某数据类的最新缓存样本（不访问机床），机台数据类如 CNCStatus、OEE、Count、Cycle、TimeData、ToolLife 等，机组数据类为 GroupCount、GroupCumulativeTime、GroupOEE；无效数据类时错误消息列出可选值	type、machineID / groupID（二选一）、tag（可选）	readTaskData、readGroupTaskData
read_machine	从机床实时读取一台机台的多项数据，items 可选 status（状态详情）、alarm（当前警报）、position（坐标）、load（负载）、feedAndSpindle（进给与转速）、toolNumber（当前刀号）、timeData（时间数据）、count（计数），默认 status 与 alarm；各项结果放在同名字段下，失败项放在 errors 中	machineID、items（可选）、channel（可选）	readCNCStatusDetails、readAlarm、readPosition、readLoad、readFeedAndSpindle、readCurrentToolNumber、readTimeData、readCount
read_tool_life	读取刀具寿命，detailed=true 时返回详情	machineID、toolNum / groupNum / offsetNum（均可选，省略则读取全部）、detailed（可选）	readToolLife、readToolLifeDetails
list_programs	读取机台程序文件列表	machineID、dirAtCNC / subDir / startPrgNo（均可选）	readProgramList
read_current_program	读取当前运行程序（目录、文件名与内容），内容超过 maxChars 时截断并标记 truncated、totalChars	machineID、dirAtCNC / subDir（均可选）、maxChars（可选，默认 20000，0 为不限）	readCurrentProgram

9.4.3. 数据分析

工具	说明	参数	对应接口
analyze	机台或机组的时间窗口统计，kind 可选 oee、alarm、count、cycle、overall；时间窗口须小于 31 天，interval（秒）将窗口切分为子区间；返回 {kind, machineID 或 groupID, window, data}	kind、start、machineID / groupID（二选一）、end（可选）、interval（可选）、enableCountPerProgram（可选，仅 count）	机台分析、机组分析
query_history	查询机台或机组内机台的历史数据，type 为数据类（如 CNCStatus、AlarmLog、AlarmHistory、Count、OEE、Heartbeat）；默认按时间升序，newestFirst=true 取最新的若干条；返回 {type, machineID 或 groupID, window, order, count, limitReached, data}	type、start、machineID / groupID（二选一）、end（可选）、limit（可选，默认 200，0 为不限）、newestFirst（可选）	machine、group-machine、query（仅 newestFirst）

9.4.4. 系统信息

工具	说明	参数	对应接口
get_system_info	一次返回 gateway（标识与别名，不含 accessToken）、core（版本）、license（许可）、services（服务状态与队列）、time（当前时间、网关时区与偏移）、hardware（硬件资源）；includeNetwork=true 时附带 network（网络适配器）；失败的分项放在 errors 中	includeNetwork（可选）	gateway-info、info、license-info、service-status、time-zone、hardware-resources、network-adapters
get_error_log	查询网关接口错误日志，limit 保留最新的若干条；返回 {window, total, returned, truncated, data}	start（可选）、end（可选）、limit（可选，默认 200）	/api/log/error

9.5. 返回结果与错误

直通类工具调用成功时，返回内容即对应 HTTP 接口的返回报文（JSON 字符串），字段说明见各接口章节；机台配置中的 password、fileServerPassword 与网关信息中的 accessToken 不经 MCP 返回。

组合类工具返回合并后的 JSON 对象：list_machines、list_groups 返回精简行；get_fleet_status、read_machine、get_system_info 按分项组织，失败的分项以错误消息放在 errors（或 statusError、connection.error）中，其余分项正常返回；analyze、query_history、get_error_log 在 window 中回显解析后的时间窗口（startUnix、endUnix、start、end、timeZone），原接口返回放在 data 中。

工具调用失败时，返回 MCP 的工具错误（isError），错误消息格式为：

{接口地址} failed: {错误码名称}({errorCode}) {错误说明}. Hint: {处理提示}

例如查询一个不存在的机台：

/cnc/readCNCStatusDetails failed: GENERAL_MACHINE_ID_NOT_EXISTED(10003). Hint: Unknown or inactive machineID; call list_machines to get valid IDs.

其中 errorCode 与 HTTP 接口的错误码完全一致，含义见 5.2. 错误处理。HTTP 接口以 200 返回的信息级错误（如任务未就绪 1303）在 MCP 中同样作为工具错误返回。参数校验错误（无效的数据类、时间写法、同时给出 machineID 与 groupID 等）的错误消息中列出可接受的取值。

9.6. 使用限制

• 工具均为只读，不提供任何修改配置、控制机台、传输文件的能力；如需写入操作，请使用 HTTP 接口。
• 以下接口不提供 MCP 工具：文件传输与日志下载等返回文件流的接口、用户配置与安全设置等涉及敏感信息的接口。自由查询历史数据的 query 接口不单独提供，仅由 query_history 的 newestFirst 选项以固定过滤条件调用（启用安全控制时该用户需被授权 /api/db/query）。
• 工具返回的数据量受机台响应与时间窗口影响，分析类工具建议限定较短的时间窗口，历史数据查询建议使用 limit 参数。
• 没有实际机床时，可使用模拟机台测试 MCP 工具（在3.3.1. 添加机台中添加）。