Using the Kanzi Monitor MCP server¶

The Kanzi Monitor MCP server is a Python tool that exposes Kanzi Monitor Overwatch commands as structured tools for AI assistants such as Claude Code and Claude Desktop. It connects to the Kanzi Monitor console over TCP or serial and enables AI agents to inspect and control a running Kanzi application through the Model Context Protocol.

You can find the tool in tools/monitor-mcp-server/. See tools/monitor-mcp-server/README.md for the full reference.

How the Kanzi Monitor MCP server works¶

Claude Code/Desktop  ──(stdio)──>  MCP Server (Python)  ──(TCP or Serial)──>  Monitor Console  ──>  Kanzi App

The MCP server runs as a subprocess of the AI assistant. It receives tool calls over standard I/O using the Model Context Protocol and forwards them as overwatch.* commands to the Kanzi Monitor console. The MCP server returns JSON responses from Kanzi Monitor to the AI assistant as structured tool results. Large responses such as images and big JSON payloads are saved to temporary files to reduce context window consumption.

Requirements¶

Python 3.10 or later
mcp package: pip install "mcp>=1.0.0"
For serial connections: pyserial-asyncio-fast: pip install pyserial-asyncio-fast
A running Kanzi application with Kanzi Monitor and ServiceOverwatchEnabled=1

Setting up the Kanzi Monitor MCP server¶

Setting up with Claude Code¶

The examples below assume that Kanzi Monitor is installed to the default location in your Kanzi workspace: Engine/plugins/monitor/.

Create a .mcp.json file in the root of your Kanzi application project:

{
  "mcpServers": {
    "kanzi-monitor": {
      "command": "python",
      "args": ["../../Engine/plugins/monitor/tools/monitor-mcp-server/kanzi_monitor_mcp.py"],
      "env": {
        "KANZI_MONITOR_HOST": "127.0.0.1",
        "KANZI_MONITOR_PORT": "56000"
      }
    }
  }
}

Setting up with Claude Desktop¶

To set up the Kanzi Monitor MCP server with Claude Desktop:

Open the Claude Desktop MCP settings file (claude_desktop_config.json).

Add the following entry:

{
  "mcpServers": {
    "kanzi-monitor": {
      "command": "python",
      "args": ["C:/KanziWorkspace/Engine/plugins/monitor/tools/monitor-mcp-server/kanzi_monitor_mcp.py"],
      "env": {
        "KANZI_MONITOR_HOST": "127.0.0.1",
        "KANZI_MONITOR_PORT": "56000"
      }
    }
  }
}

Replace C:/KanziWorkspace with the actual path to your Kanzi workspace.

Configuring the connection¶

All configuration uses environment variables in the MCP server configuration.

Variable	Default	Description
`KANZI_MONITOR_HOST`	`127.0.0.1`	Monitor TCP host.
`KANZI_MONITOR_PORT`	`56000`	Monitor TCP port.
`KANZI_MONITOR_TIMEOUT`	`30` (TCP) / `120` (serial)	Command timeout in seconds.
`KANZI_MONITOR_SERIAL_PORT`	(empty)	Serial device path, for example `COM3` or `/dev/ttyUSB0`. When you set this variable, the server uses serial instead of TCP.
`KANZI_MONITOR_BAUD_RATE`	`115200`	Serial baud rate. Used only with `KANZI_MONITOR_SERIAL_PORT`.

To connect over serial instead of TCP, set KANZI_MONITOR_SERIAL_PORT in the environment:

{
  "mcpServers": {
    "kanzi-monitor": {
      "command": "python",
      "args": ["../../Engine/plugins/monitor/tools/monitor-mcp-server/kanzi_monitor_mcp.py"],
      "env": {
        "KANZI_MONITOR_SERIAL_PORT": "COM3",
        "KANZI_MONITOR_BAUD_RATE": "115200"
      }
    }
  }
}

Available tools¶

The MCP server exposes all Overwatch commands as structured tools.

Tool	Description
`get_scene_tree`	Gets the node tree as JSON. Accepts an optional depth limit.
`get_node_properties`	Gets all properties of a node.
`set_node_property`	Sets a property value on a node.
`get_resources`	Lists loaded resources with memory usage.
`get_all_resources`	Lists all resources, including unloaded ones.
`get_resource_info`	Gets detailed metadata for a resource by index. For textures, this includes type, face count, slice count, and a cubemap flag.
`get_texture_preview`	Gets a preview of a texture. Saves as a temporary PNG file. Accepts an optional `face` argument (0–5) to preview a single cubemap face.
`purge_resources`	Purges unused resources.
`get_framebuffers`	Lists FBO-backed render targets.
`get_render_passes`	Gets the render pass tree.
`get_render_pass_preview`	Gets a preview of a render pass output. Saves as a temporary PNG file.
`take_screenshot`	Captures a screenshot of the application. Polls the two-phase capture protocol internally so a single call returns the image. Saves as a temporary PNG file.
`get_performance`	Gets current FPS, frame times, rendering statistics, GPU object counts, and staging buffer usage.
`get_app_performance`	Gets frames-per-second (FPS) information from the Kanzi Domain main loop.
`get_performance_info_level`	Gets the PerformanceInfo logging level.
`set_performance_info_level`	Sets the PerformanceInfo logging level.
`list_watchers`	Lists active performance watchers.
`add_watcher`	Adds a metric watcher that triggers a command when a threshold is crossed.
`remove_watcher`	Removes a watcher by ID.
`reset_watcher`	Resets a triggered watcher to active.
`clear_watchers`	Removes all watchers.
`capture_trace`	Captures a Monitor profiling trace to file. Writes one file per active writer — `.json` for `chrometrace`, `.perfetto-trace` for `perfetto`.
`fetch_trace`	Fetches the most recent `.json` (chrometrace) Monitor profiling trace as a JSON string. Returns an error pointing at `fetch_perfetto_trace` if only the `perfetto` writer ran.
`fetch_perfetto_trace`	Fetches the most recent `.perfetto-trace` (native Perfetto protobuf) capture. The binary is transported as base64 over the line protocol, decoded by the tool, and persisted to a temp file. Returns `{file, path, size}` — pass `path` to Perfetto UI for visualisation.
`capture_kztrace`	Captures a kzTrace snapshot (engine-native tracing, requires Debug or Profiling build).
`fetch_kztrace`	Fetches the most recent kzTrace as JSON.
`list_writers`	Lists registered trace writers with name, description, and current active state.
`activate_writer`	Activates a trace writer by name (e.g. `chrometrace`, `perfetto`). Use `list_writers` to see what is registered.
`deactivate_writer`	Deactivates a trace writer by name. Deactivating all writers stops trace output.
`get_data_sources`	Gets all data sources and DataObject trees.
`set_data_value`	Sets a value in a DataObject tree.
`get_status`	Gets Overwatch service status.
`get_fonts`	Gets all active FontRuntimes with font identity, style, glyph cache state, metrics, and node info.
`get_font_glyph_cache_preview`	Gets a preview of a font’s glyph cache texture. Saves as a temporary PNG file.
`set_glyph_cache_size`	Sets the glyph cache texture size for newly created caches. Requires `OverwatchPropertyChangeEnabled`.
`get_graphics_info`	Gets graphics backend and device information.
`get_logs`	Gets recent log entries.
`set_log_buffer_size`	Sets the log buffer size at runtime.
`get_log_config`	Gets the current log buffer configuration.
`get_log_diagnostics`	Gets KanziLog trace pipeline diagnostics.
`get_ui_visibility`	Gets the Monitor UI overlay visibility status for each node tree.
`toggle_ui`	Shows or hides the on-screen UI overlay. Accepts an optional `node_tree` parameter to target a specific node tree.
`get_basicui_screens`	Lists available BasicUI overlay screens and the current selection.
`set_basicui_screen`	Switches to a BasicUI overlay screen by index.
`get_font_scale`	Gets the current BasicUI overlay font scale.
`set_font_scale`	Sets the BasicUI overlay font scale.
`get_idle_suspend`	Gets the current MainLoopScheduler SuspendWhenIdle state.
`set_idle_suspend`	Enables or disables MainLoopScheduler SuspendWhenIdle.
`send_command`	Sends a raw Kanzi Monitor command.
`quit_application`	Quits the Kanzi application.

Response size optimization¶

The MCP server automatically reduces large responses to avoid consuming the AI assistant’s context window:

Image responses (take_screenshot, get_texture_preview, get_render_pass_preview): Raw RGBA pixel data is converted to a temporary PNG file. All images are automatically flipped vertically to match screen orientation (GPU readback data is bottom-up). The tool returns the image dimensions, file path, and any non-pixel metadata. The AI assistant can then read the PNG file when it needs to see the image.
Binary trace responses (fetch_perfetto_trace): .perfetto-trace files are protobuf binaries and cannot traverse the text-mode command protocol as-is. The C++ side base64-encodes the bytes inside a JSON envelope; the MCP tool decodes the base64 and writes the resulting binary to a temporary .perfetto-trace file, returning the path. The AI assistant can pass the path on to a trace analyser or open it in Perfetto UI.
Large text responses (get_scene_tree, get_resources, get_all_resources, fetch_trace, get_data_sources): When a response exceeds 50 KB, it is written to a temporary JSON file. The tool returns the file path and a preview of the first 200 lines.

Temporary files are written to the system temp directory and are not automatically deleted.

Troubleshooting¶

MCP server does not connect¶

Verify that the Kanzi application runs with the Kanzi Monitor plugin loaded.
Check that ServiceOverwatchEnabled=1 is set in kanzimonitor.cfg.
Confirm that the host and port match your kanzimonitor.cfg settings. The RemoteConsolePort setting defaults to 56000.

Tools return timeout errors¶

take_screenshot polls the two-phase capture protocol internally, so a single call returns the image. If it reports Screenshot timed out — render stage did not complete, the application is not rendering new frames. When running in Studio Preview, ensure Allow preview to update if not in focus is enabled.
Increase KANZI_MONITOR_TIMEOUT for slow devices or serial connections.

Serial connection fails¶

Install pyserial-asyncio-fast: pip install pyserial-asyncio-fast.
Verify the serial port name, for example COM3 on Windows or /dev/ttyUSB0 on Linux.
Ensure that SerialConsoleEnabled=1 is set in kanzimonitor.cfg.

Property changes have no effect¶

Ensure that OverwatchPropertyChangeEnabled=1 is set in kanzimonitor.cfg.