MCP for AI agents

The gatOS Model Context Protocol server is the first-class interface for an AI agent operating Kitten Space Agency. It reads the same immutable telemetry snapshots and submits the same game-thread commands as /sim, HTTP, MQTT, and serial, but presents them as logical JSON documents and agent-sized operations.

It is deliberately not a one-tool-per-/sim-file mirror. An agent asks for a vessel, celestial, kitten, world, or runtime feature as a coherent document. It then acts through explicit tools such as gatos.ignite_engines, gatos.vessel_control, gatos.execute_batch, and gatos.schedule_batch.

Connect and make a first callEndpoint, discovery flow, configuration, and a short first-session sequence.

Understand the wire contractFreshness, pagination, envelopes, errors, identifiers, phases, and limits.

Run an agent safelyObserve–act–verify, same-tick and timed coordination, camera work, and errno recovery.

Browse all 28 toolsRead, control, media, debug, atomic batch, and timed schedule tools.

Browse all 9 resourcesFixed JSON resources and RFC 6570 templates for the same presenters.

The versioned contract

This section is the task-oriented reference. The exhaustive public contract and maintenance rules live in SPEC_MCP.md.

Connect locally

MCP uses stateless Streamable HTTP at http://127.0.0.1:4243/mcp by default. The preferred port falls back to an ephemeral one when occupied. Configure mcp_enabled, mcp_bind_host, and mcp_preferred_port in gatos.toml; use a specific interface IP or 0.0.0.0 for intentional network access. MCP has no bearer token, so non-loopback reachability also exposes its control tools. The status window reports the actual bound port.

1. Connect an MCP client to the bound /mcp endpoint. 2. Call gatos.get_capabilities to learn which optional systems and actions are currently available. 3. Read gatos.get_world and the vessel or celestial documents needed for the task. 4. Use the narrowest logical control tool that expresses the user’s intent. 5. Use gatos.wait to synchronize the next planning turn with the simulation.

The complete observe–act–verify loop and task sequences live in the agent playbooks.

Choose the right interface

Intent	Best starting point
Understand the current simulation	gatos.get_world
Discover ids	gatos.list_vessels, gatos.list_celestials, or gatos.list_kittens
Inspect one entity	gatos.get_vessel, gatos.get_celestial, or gatos.get_kitten
Inspect feature-owned state	gatos.get_runtime_state
Perform one ordinary flight action	Common vessel actions or gatos.vessel_control
Change one fitted module	gatos.module_control
Paint a vehicle, part, or EVA	gatos.paint_control
Coordinate same-tick changes	gatos.execute_batch
Run a timed sequence	gatos.schedule_batch and gatos.schedule_control
Use a known URI through resources/read	Resource directory

Read coherent JSON

Pass detail:"full" to gatos.get_world for the complete current snapshot. A vessel read can select flight, orbit, environment, propulsion, resources, power, control, modules, encounters, parts, paint, or all. Selected sections include every matching nested object.

Lists return 50 entities by default and accept at most 1,000 per page. Follow next_cursor for the rest. gatOS never measures, caps, or truncates MCP JSON results. Each snapshot-derived result carries snapshot_sequence and ut, so the caller can judge freshness even when the simulation advances between pages.

Control with intent

Use explicit triggers when they exactly match the request:

gatos.ignite_engines({ vessel_id: "Hunter" })
gatos.shutdown_engines({ vessel_id: "Hunter" })
gatos.activate_stage({ vessel_id: "Hunter" })

The logical families cover vessel and module controls, the programmable camera, camera tracks, audio, schedules, debug/game manipulation, runtime render FX, and vehicle/EVA paint. The advanced gatos.command envelope remains the complete-coverage backstop for every canonical gatOS action.

Coordinate commands

gatos.execute_batch validates up to 64 commands and submits them once as an ordered, same-phase, same-tick group. gatos.schedule_batch is the JSON timed-batch counterpart: entries use absolute at_ms offsets on the existing render, wall, or ut clock and may mix command phases.

Milliseconds and seconds

Batch schedule offsets and schedule-player positions are milliseconds. Camera-track authoring uses seconds. The MCP tools preserve this distinction.

Important game caveats

• Read controllable before ordinary flight control. KSA can ignore a vessel without a control module.
• CCI state, burns, teleport, and default impulses are relative to the vessel’s current parent body.
• RCS translation and rotation are body-axis bang-bang commands. They are inert while RCS mode is disabled, and focus/UI/large warp can clear their latches.
• Solver-phase flight-computer commands take effect on the next solver step. Same-tick batches cannot mix them with Frame commands.
• Optional control, debug, camera, audio, schedule, IVA, and FX gates remain authoritative.
• /sim/display is intentionally absent. It is an infinite Kitty terminal-video stream for visual TTY sessions, not a logical JSON agent interface.

Complete directories

Tools

Every callable operation has its own schema, example, operation mapping, result, gate, error, and safety reference.

Open the tool directory →

Resources

Every fixed resource and URI template has a dedicated page describing parameters, document shape, freshness, and equivalent tool.

Open the resource directory →