Connect and get started

gatOS hosts MCP inside the C# game mod. There is no stdio proxy, guest endpoint, or bearer token.

Endpoint and configuration

The default endpoint is:

http://127.0.0.1:4243/mcp

The listener is enabled by default. In gatos.toml:

mcp_enabled = true
mcp_bind_host = "127.0.0.1"
mcp_preferred_port = 4243

Set mcp_bind_host to a specific host-interface IP or 0.0.0.0 for all IPv4 interfaces. Set the preferred port to 0 to request an ephemeral port. A nonzero port is clamped to 1024..65535; if it is occupied, gatOS falls back to an ephemeral port. Read the actual port from the gatOS status window or transport status surfaces.

Transport behavior

• Streamable HTTP at POST /mcp; the bind host defaults to 127.0.0.1.
• Stateless request handling: no Mcp-Session-Id, GET event stream, DELETE, legacy /sse, or /message endpoint.
• A specific-address bind validates the configured Host. Origin may be absent for native clients; when present it must match. A wildcard bind accepts the authority used by the client.
• No CORS response headers and no bearer token.
• Each POST stays open until its handler completes, so command and wait calls preserve request-level backpressure.
• Current discovery and compatible initialize-capable clients are handled by the official C# MCP SDK.

A non-loopback bind exposes MCP reads and control tools without authentication. Limit reachability with the selected interface and the host firewall.

First agent sequence

1. Connect your Streamable HTTP MCP client to the actual bound endpoint. 2. Call gatos.get_capabilities and retain its gates, limits, phases, and action metadata. 3. Call gatos.get_world with detail:"summary". 4. Discover a target with gatos.list_vessels and read it with gatos.get_vessel. 5. Confirm controllable, the target raw id, its current parent, and any relevant feature gates. 6. Submit one narrow logical action, such as gatos.ignite_engines or gatos.vessel_control. 7. Call gatos.wait with the previous snapshot_sequence, then re-read state before planning again.

A minimal interaction

gatos.get_capabilities({})
gatos.get_world({ "detail": "summary" })
gatos.get_vessel({ "id": "active", "include": ["flight", "propulsion", "resources"] })
gatos.vessel_control({ "operation": "throttle", "vessel_id": "Hunter", "value": 0.35 })
gatos.ignite_engines({ "vessel_id": "Hunter" })
gatos.wait({ "after_sequence": 812, "timeout_ms": 30000 })

These examples show tool names and JSON arguments, not a vendor-specific client library syntax. Your MCP client supplies the JSON-RPC and HTTP framing.

Shutdown and cancellation

Closing a request cancels cancellable handlers such as gatos.wait. A command cancelled before it is admitted to the game-thread queue is abandoned. Once the game thread begins executing a command, the action is not reversible. Mod shutdown cancels active requests and disposes the listener before the shared stores.

Next, read shared conventions or browse the tool directory.