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.
`get_texture_preview`	Gets a preview of a texture. Saves as a temporary PNG file.
`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. 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 application-level performance information.
`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.
`fetch_trace`	Fetches the most recent Monitor profiling trace as JSON.
`capture_kztrace`	Captures a kzTrace snapshot (engine-native tracing, requires Debug or Profiling build).
`fetch_kztrace`	Fetches the most recent kzTrace as JSON.
`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_graphics_info`	Gets graphics backend and device information.
`get_logs`	Gets recent log entries.
`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.
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¶

Some commands, such as take_screenshot, require two calls. The first call schedules the capture and the second retrieves the data.
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.