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 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 Overwatch commands as structured tools.

Note

All of these tools are available on Kanzi 3.6. The resource-detail, preview, and framebuffer tools (get_all_resources, get_resource_info, get_texture_preview, get_framebuffers, get_render_passes, get_render_pass_preview) read resources and render targets through the Kanzi 3.6 backport, using GPU readback for GPU-only textures. take_screenshot additionally requires the application to drive the per-frame service contract (see Using the Overwatch service); if it does not, the tool reports a pending status rather than an image. GPU-read pixels arrive in GL bottom-up row order and take_screenshot and the GPU-readback preview tools flip them to top-down before encoding, so the saved PNG matches the on-screen orientation. get_resource_info reports each texture’s type, face count, slice count, and cubemap flag, and get_texture_preview accepts a face argument to preview an individual cubemap face. Resource enumeration is loaded-only on Kanzi 3.6, so get_all_resources returns the same set as get_resources. See Release notes.

Tool	Description
`get_scene_tree`	Gets the node tree as JSON. Accepts an optional depth limit.
`get_node_properties`	Gets a node’s locally-set property values (no binding-source info on Kanzi 3.6).
`set_node_property`	Sets a property value on a node.
`get_resources`	Lists loaded resources with memory usage.
`purge_resources`	Purges unused resources.
`get_performance`	Gets current FPS, frame times, and render statistics.
`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.
`get_idle_suspend`	Gets whether the main loop suspends when the application is idle.
`set_idle_suspend`	Sets whether the main loop suspends when the application is idle.
`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 profiling trace to file.
`fetch_trace`	Fetches the most recent trace as JSON.
`get_data_sources`	Gets all data sources and DataObject trees.
`set_data_value`	Sets a value in a DataObject tree.
`get_fonts`	Lists the glyph caches in use by active text nodes as JSON.
`get_font_glyph_cache_preview`	Gets a base64 RGBA preview of a glyph cache atlas texture.
`set_glyph_cache_size`	Sets the glyph cache texture size for newly created caches.
`get_status`	Gets Overwatch service status.
`get_graphics_info`	Gets graphics backend and device information.
`get_logs`	Gets recent log entries.
`get_log_config`	Gets the current log buffer configuration (max and current entry count).
`set_log_buffer_size`	Sets the log buffer size at runtime.
`set_graphics_logging`	Enables/disables graphics API call logging (optional state dump and frame limit).
`get_graphics_logging`	Gets the current graphics API call logging state.
`get_log_diagnostics`	Gets KanziLog trace pipeline diagnostics.
`toggle_ui`	Shows or hides the on-screen UI overlay. Optional `node_tree` parameter.
`get_ui_visibility`	Gets whether the on-screen Monitor UI overlay is visible.
`get_basicui_screens`	Lists the available BasicUI overlay screens.
`set_basicui_screen`	Selects the active BasicUI overlay screen by index.
`get_font_scale`	Gets the on-screen overlay font scale.
`set_font_scale`	Sets the on-screen overlay font scale.
`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:

Large text responses (get_scene_tree, get_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¶

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.