MCP & Control Port
Relevant source files
The following files were used as context for generating this wiki page:
The Model Context Protocol (MCP) server and Control Port provide an interface for AI agents and external tools to interact with a running cyrus game instance. This system allows for automated inspection, testing, and manipulation of game state without human manual input.
The MCP server operates over standard I/O (stdio) and translates MCP tool calls into game-specific commands. These commands travel over a TCP Control Port to the game's internal server. This architecture ensures the MCP server can start before the game and survives game restarts by opening a fresh connection for each request.
Sources: crates/cyrus-mcp/src/main.rs:1-6, crates/cyrus-mcp/README.md:1-5
Architecture and Data Flow
The system consists of three main layers: the AI Agent (e.g., Claude Code), the cyrus-mcp server, and the game's control server. The cyrus-mcp server acts as a bridge, utilizing the rmcp crate to implement the protocol.
The diagram shows the communication flow from an external agent through the MCP bridge to the game engine.
The MCP server uses the CYRUS_CONTROL_ADDR environment variable to locate the game's control port, defaulting to 127.0.0.1:7117.
Sources: crates/cyrus-mcp/src/main.rs:11-13, crates/cyrus-mcp/README.md:9-11, crates/cyrus/README.md:14-16
Available Tools and Commands
The MCP server exposes a variety of tools that map to specific game functionalities. These include state inspection, environment manipulation, and script debugging.
| Tool Name | Parameters | Description |
|---|---|---|
ping | None | Validates that the game is running and reachable. |
state | None | Returns app state, scene name, player position/rotation, and frame counter. |
screenshot | path (optional) | Captures the game window as a PNG and returns the image/path. |
teleport | x, y, z | Moves the player to specific engine-space coordinates. |
input | key, action | Injects keyboard events (press, release, tap). |
load_scene | name | Loads a specific map stem (e.g., ISLAND, START). |
skip_startup | None | Bypasses splash/title screens and stops at the book menu. |
cheat | name, value | Sets/toggles cheats or lists state via oracle. |
scripts | offset, limit | Inspects logical script actor state. |
Sources: crates/cyrus-mcp/src/main.rs:116-258, crates/cyrus-mcp/README.md:6-9
Control Server Logic
The game's control server handles TCP framing and command application. It remains active even in --headless mode, allowing for scene export and remote inspection.
The sequence illustrates the short-lived nature of the connection per tool call.
Sources: crates/cyrus-mcp/src/main.rs:16-24, crates/cyrus/README.md:11-12, crates/cyrus-game/README.md:12-15
Script Inspection and Debugging
Advanced tools allow developers to step through script execution. The step_script tool provides access to specific execution stages such as ordinary_main, entry, main, and interrupt. These tools are for inspection only and do not enable automatic gameplay.
- Stages:
prepare_spatial,snapshot,transform,animation,tasks, etc. - Requirements: Stages like
tasksrequire an explicitframe_scalewith eight fractional bits.
Sources: crates/cyrus-mcp/src/main.rs:90-111, crates/cyrus-mcp/README.md:28-40
Configuration and Setup
The MCP server is registered for specific agents via configuration files:
- Claude Code:
.mcp.json(pre-approved by.claude/settings.json). - Codex:
.codex/config.toml.
For testing, you can run just smoke-mcp to launch a headless game and drive it through the MCP server end-to-end.
Sources: crates/cyrus-mcp/README.md:9-14, AGENTS.md:143-145
State Reporting
The state tool provides detailed information about the game's current context.
- Menu State: Reports page ID, selection, and movie progress.
- Music State: Reports
music_track(CD track) andmusic_pausedstatus. - Scene State:
state.scene_readyindicates if asynchronous scene dependencies are loaded.
Sources: crates/cyrus-mcp/README.md:15-20, crates/cyrus/README.md:104-106, crates/cyrus/README.md:108-112
The MCP and Control Port system enables high-fidelity automated verification. By providing fine-grained control over script execution and state inspection, it allows agents to perform repeatable comparisons between cyrus and the original game.