9. MCP Service

The gateway has a built-in MCP (Model Context Protocol) server that exposes machine data, data analysis, and gateway status as “tools” for AI clients (Claude Code, Claude Desktop, MCP Inspector, and any other MCP-capable application or agent), so machines can be queried in natural language without writing HTTP requests by hand.

Internally, MCP tools go through exactly the same processing pipeline as the HTTP interfaces. Passthrough tools (get_machine, read_tool_life, list_programs, read_task_data) return exactly what the corresponding HTTP interface returns; composite tools (get_fleet_status, read_machine, analyze, query_history, get_system_info, …) call several interfaces in one go and merge or wrap the results as described in 9.5. Results and Errors. For field definitions, see the sections under 5. HTTP Communication.

9.1. Basics

The MCP server endpoint is /mcp, served on the same port as the HTTP interfaces:

http://{Gateway IP}/mcp

Caution

The MCP service is disabled by default; while it is off, /mcp returns HTTP 404. Turn the switch on under 3.6.8. MCP Settings and save; it takes effect immediately, with no restart of the gateway or its services.

The transport is the MCP standard Streamable HTTP: the client POSTs JSON-RPC messages with the headers Content-Type: application/json and Accept: application/json, text/event-stream. The server is stateless — every tool call is an independent HTTP request.

13 read-only tools are currently provided, covering machine configuration, live status, cached snapshots, data analysis, and gateway system information; see 9.4. Tool List. No MCP tools are provided for interfaces that write data, control machines, or transfer files — those remain available through the HTTP interfaces only.

Designed for agents:

• The initialize response carries server instructions: the recommended call order, time parameter forms, the meaning of machine status values, common error codes with what to do about them, and the documentation URL.
• Every tool is annotated read-only and idempotent (readOnlyHint, idempotentHint), so clients that honour the annotations can call them without confirmation.
• All time parameters accept several forms (see 9.4. Tool List); results echo the time window resolved in the gateway’s time zone.
• Error messages carry a hint, and composite tools report errors per section instead of failing as a whole.

Note

The cloud platform (Hub) also provides an MCP server at https://{cloud platform address}/mcp. Its tool list is identical to the gateway’s; calls are forwarded by the cloud platform to the designated gateway for execution. For authentication, see 9.2.2. Cloud Platform Authentication.

9.2. Authentication

9.2.1. Gateway Authentication

The MCP server uses the same authentication as the HTTP interfaces; see 5.3. Authentication Methods. Send Authorization: Bearer <token> in the request headers, where the token is either a token obtained via 5.3.1. JWT Method or a key generated via 5.3.2. Secret Key Method (an administrator generates it for the user under 3.12.1.3.2. User Security Settings). If no credentials or invalid credentials are supplied, HTTP 401 is returned.

Caution

A JWT token is valid for 24 hours; once it expires, the MCP client keeps failing every call. MCP client configurations are usually kept long-term, so a permanent secret key is recommended.

The other access controls apply as well:

• IP whitelist: when enabled under 3.6.6. HTTP Settings, the source IP of a /mcp request must be in the whitelist, following the same rules as /api; see 5.3.3. IP Whitelist.
• Per-user authorized APIs: when Security Control is enabled, administrators may call every tool, while other users may only call the interfaces covered by their authorized API list (each interface a tool calls is matched individually, using the same configuration as HTTP requests). In a composite tool an unauthorized section is reported under errors as Forbidden: ... while the other sections still return; a single-interface tool returns an error for the call.
• With security control disabled, tools can be called without user authentication (the IP whitelist still applies).

9.2.2. Cloud Platform Authentication

When calling the cloud platform’s MCP server, send accessToken: <gateway token> in the request headers — the same rule the cloud platform’s HTTP proxy uses: the token is both the credential and the selector for which gateway executes the tool. The gateway token is the one entered under 3.6.1. Cloud Platform; for the interface see 5.9.6.1. cloud-settings - Get Cloud Platform Settings.

If the token is missing or not registered, the tool call returns Unauthorized: missing or unknown accessToken header.; if the token is valid but the corresponding gateway is not currently connected to the cloud platform, it returns GATEWAY_SERVICE_UNAVAILABLE.

9.3. Client Configuration

Using Claude Code as an example, add the gateway MCP server:

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

Add the cloud platform MCP server:

claude mcp add --transport http bivrost-hub https://cloud.example.com/mcp --header "accessToken: <gateway token>"

Other MCP clients generally use a JSON configuration of the following form:

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

To verify directly that the server is reachable, list all tools with a JSON-RPC request:

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

9.4. Tool List

Parameters marked “optional” below may be omitted, in which case the default is used. For the meaning of machineID and groupID see 4.1.1. Basics; they can be obtained with list_machines and list_groups.

Time parameters (start, end) accept the following forms and are resolved in the gateway’s time zone: a Unix timestamp (seconds; 13 digits are treated as milliseconds); ISO-8601 with an offset (2026-09-17T08:00:00+08:00); ISO-8601 or a bare date without an offset (2026-09-17T08:00, 2026-09-17, interpreted as gateway local time); a relative offset (-30m, -24h, -7d, -2w); or the keywords now, today, yesterday (the last two mean midnight of that day). end defaults to now.

Recommended call order: list_machines → get_fleet_status (plant-wide overview) → read_machine / analyze / query_history (details of one machine).

9.4.1. Configuration

Tool	Description	Parameters	Interface
list_machines	List every machine’s identity fields: machineID, name, system, model, machineType, ip, port, isActive	none	machines
list_groups	List every machine group: groupID, name, isActive, member machineIDs	none	groups
get_machine	Full configuration of one machine (credential fields excluded)	machineID	machine

9.4.2. Machine Status

Tool	Description	Parameters	Interface
get_fleet_status	The latest cached status and connection health of every machine (or of one group’s members) in one call, without contacting the machines. Per machine: connection (errorCode 0 = communication OK), status (cncStatus, adjustedStatus, alarmStatus, alarmLevel, mode, programStatus, time) and a derived state (running / idle / alarm / setup / offline / noData / inactive), plus summary counts. When the connection is down the state is offline and the cached status is flagged statusStale. Requires the machine status task; without it the state is noData	groupID (optional)	machines, group, batchReadTaskData, batchReadErrors
read_task_data	The latest cached sample of one data class (no request to the machine). Machine classes include CNCStatus, OEE, Count, Cycle, TimeData, ToolLife; group classes are GroupCount, GroupCumulativeTime, GroupOEE. An invalid class returns an error listing the valid values	type, machineID / groupID (one of them), tag (optional)	readTaskData, readGroupTaskData
read_machine	Live read of several items from one machine. items may include status (status details), alarm (active alarms), position, load, feedAndSpindle, toolNumber (current tool), timeData, count; default status and alarm. Each item is returned under its own key; failed items are listed under errors	machineID, items (optional), channel (optional)	readCNCStatusDetails, readAlarm, readPosition, readLoad, readFeedAndSpindle, readCurrentToolNumber, readTimeData, readCount
read_tool_life	Read tool life; detailed=true returns the detailed record	machineID, toolNum / groupNum / offsetNum (all optional; omit to read all tools), detailed (optional)	readToolLife, readToolLifeDetails
list_programs	List the part program files on a machine	machineID, dirAtCNC / subDir / startPrgNo (all optional)	readProgramList
read_current_program	Read the currently running program (directory, file name, content); content longer than maxChars is cut and flagged with truncated and totalChars	machineID, dirAtCNC / subDir (both optional), maxChars (optional, default 20000, 0 = unlimited)	readCurrentProgram

9.4.3. Data Analysis

Tool	Description	Parameters	Interface
analyze	Statistics over a time window for a machine or a group; kind is one of oee, alarm, count, cycle, overall. The window must be shorter than 31 days; interval (seconds) splits it into sub-windows. Returns {kind, machineID or groupID, window, data}	kind, start, machineID / groupID (one of them), end (optional), interval (optional), enableCountPerProgram (optional, count only)	Machine analysis, Group analysis
query_history	Historical rows of a machine or of a group’s machines; type is a data class (e.g. CNCStatus, AlarmLog, AlarmHistory, Count, OEE, Heartbeat). Rows are oldest-first by default; newestFirst=true returns the most recent rows. Returns {type, machineID or groupID, window, order, count, limitReached, data}	type, start, machineID / groupID (one of them), end (optional), limit (optional, default 200, 0 = unlimited), newestFirst (optional)	machine, group-machine, query (newestFirst only)

9.4.4. System Information

Tool	Description	Parameters	Interface
get_system_info	One call returning gateway (identity and alias, without accessToken), core (version), license, services (service status and queues), time (current time, gateway time zone and offset) and hardware (resource usage); includeNetwork=true adds network (adapters). Failed sections are reported under errors	includeNetwork (optional)	gateway-info, info, license-info, service-status, time-zone, hardware-resources, network-adapters
get_error_log	Query the gateway’s interface error log; limit keeps the most recent rows. Returns {window, total, returned, truncated, data}	start (optional), end (optional), limit (optional, default 200)	/api/log/error

9.5. Results and Errors

On success, a passthrough tool returns the response body of the corresponding HTTP interface (a JSON string); see each interface’s section for field descriptions. password and fileServerPassword in machine configurations and accessToken in the gateway information are never returned through MCP.

Composite tools return a merged JSON object: list_machines and list_groups return compact rows; get_fleet_status, read_machine and get_system_info are organised by section, with failed sections reported as error messages under errors (or statusError / connection.error) while the other sections return normally; analyze, query_history and get_error_log echo the resolved time window under window (startUnix, endUnix, start, end, timeZone) and put the interface’s response under data.

On failure, a tool returns an MCP tool error (isError) whose message has the format:

{interface path} failed: {error code name}({errorCode}) {error description}. Hint: {what to do next}

For example, querying a machine that does not exist:

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

The errorCode is exactly the same as that of the HTTP interfaces; see 5.2. Error Handling. Information-level errors that the HTTP interfaces return with status 200 (such as task not ready, 1303) are returned as tool errors through MCP as well. Parameter validation errors (an invalid data class or time form, machineID and groupID given together, …) list the accepted values in the message.

9.6. Limitations

• All tools are read-only; they provide no way to modify configuration, control machines, or transfer files. Use the HTTP interfaces for write operations.
• The following interfaces have no MCP tools: interfaces that return file streams (file transfer, log download) and interfaces carrying sensitive information such as user configuration and security settings. The free-form historical data query interface is not exposed as a tool of its own; only query_history’s newestFirst option calls it with fixed filters (with security control enabled, the user must be authorized for /api/db/query).
• The amount of data returned depends on machine response and the time window; for analysis tools prefer a short time window, and for historical data queries use the limit parameter.
• If no physical machine tool is available, use a mock machine to test the MCP tools (added under 3.3.1. Adding a Machine).