MCP

The Model Context Protocol (MCP) integration lets AI assistants like Claude Code and Cursor inspect and interact with a running Turian game in real time. Instead of guessing at state, an LLM can query the actual scene, entities, components, and performance metrics.

How it works

Claude Code / Cursor
      │  MCP (stdio, JSON-RPC 2.0)
      ▼
turian-cli mcp
      │  Remote Debug Protocol (TCP, port 7777)
      ▼
  Running game (debug server enabled)

turian-cli mcp bridges the two protocols. It reads MCP requests from stdin, forwards them to the game's debug server over TCP, and returns structured results.

Quick start

1 — Enable the debug server in your game

In your game's entry point, start the debug server before the main loop:

const debug = @import("debug");

var srv = debug.Server.init(allocator, .{});
defer srv.deinit(io);
try srv.start(io, .{ .ctx = &world, .getFn = myWorldProvider });

The server listens on 127.0.0.1:7777 by default.

2 — Configure your MCP client

Claude Code (~/.claude/mcp.json or project .mcp.json):

{
  "mcpServers": {
    "turian": {
      "command": "turian-cli",
      "args": ["mcp"]
    }
  }
}

With auth token (if the debug server was started with --token):

{
  "mcpServers": {
    "turian": {
      "command": "turian-cli",
      "args": ["mcp", "--token", "my-secret"]
    }
  }
}

Custom host/port:

{
  "mcpServers": {
    "turian": {
      "command": "turian-cli",
      "args": ["mcp", "--host", "192.168.1.10", "--port", "7778"]
    }
  }
}

3 — Start your game and ask questions

Once the game is running and Claude Code is connected, you can ask:

"What scenes are loaded?"
"Inspect the Player entity."
"What are the current FPS and memory usage?"
"List all entities with a Camera component."

Available tools

Read tools

Tool	Description
`list_scenes`	All currently loaded scenes and their state
`inspect_scene`	Every entity in a scene with component summary
`find_entities`	Filter entities by name substring or component type
`scene_summary`	Compact full snapshot for LLM orientation
`inspect_entity`	Transform + all component fields for one entity
`get_component`	Field values of a specific component on an entity
`get_metrics`	FPS, frame time, memory, draw calls, ECS counts
`get_schema`	Schema of all built-in component types
`list_assets`	Project assets (guid, path, type)
`inspect_material`	Inspect one asset by GUID
`capture_profiler`	Latest profiler frame (counters + zones)
`inspect_memory`	Allocator memory usage
`list_errors`	Recent engine warnings/errors

Write tools (read-write server + confirm: true)

Tool	Description
`modify_component`	Set a component field
`set_transform`	Set position/rotation/scale
`spawn_entity`	Create a new entity
`destroy_entity`	Remove an entity
`reload_asset`	Hot-reload an asset

Write tools use a confirmation gate: the first call returns a preview; pass confirm: true to actually apply the change.

CLI reference

turian-cli mcp [--host <addr>] [--port <n>] [--token <secret>]

Flag	Default	Description
`--host`	`127.0.0.1`	Debug server hostname or IP
`--port`	`7777`	Debug server port
`--token`	(empty)	Auth token (must match server's `--token`)

turian-cli mcp exits when stdin closes — the MCP client controls its lifetime.

Protocol details

Transport: JSON-RPC 2.0 over stdio, newline-delimited
MCP version: 2024-11-05
Capabilities: tools (list + call)
Read-only by default: mutation tools return an error unless the debug server is started in read-write mode

Remote Debug Protocol — the TCP layer underneath
Runtime Introspection — the engine API both layers consume
CLI Reference — other turian-cli commands

← All docs Edit this page

MCP