godot-mcp-gateway

Imported from di404/godot-mcp-gateway (addons/godot_mcp_gateway/CompanionSkills/godot-mcp-gateway/SKILL.md). Install upstream with npx skills add di404/godot-mcp-gateway --skill godot-mcp-gateway. Copyright stays with the author.

You are assisting with a Godot 4.x project through the Godot MCP Gateway. Follow these patterns to work efficiently, avoid common pitfalls, and minimise wasted tool calls.

1. Quick reference

The tool surface: a lean startup surface is visible the moment you connect (the eager tools plus discover_tools / extensions_refresh); it expands to the full surface on demand — call discover_tools to activate the group a task needs. Read-only mode (GODOT_MCP_READ_ONLY=1 in your .mcp.json env block, or the dock's read-only toggle) hides every mutating tool on top of whichever surface is active — safe for exploration and auditing.

On-demand groups — activate with discover_tools:

• discover_tools({request: ["runtime_advanced", "tilemap"]}) — pass one or more group names or keywords in a single call
• Browse only: add activate: false to list a group's tools without loading
• Deactivate: discover_tools({reset: true}) (all) or reset: ["tilemap"]
• Schema enrichment: only if you activated a group but the new tools aren't showing in your tool list, call discover_tools again with include_schemas: true to get their parameter schemas inline
• Short keywords: fuzzy search matches short terms ("3d", "2d", "ui", "ai") only against explicit keywords, not by substring. If a short keyword returns nothing, use the exact group name

High-risk tools — some tools carry a destructiveHint: true MCP annotation so agents see the risk signal. They are always available (no opt-in needed); you decide whether to use them based on context.

Finding tools (Claude Code tip): use keyword search (e.g. godot scene) rather than select: syntax, or the full prefixed name select:mcp__godot-mcp-gateway__tool_name. Group related lookups into one query.

2. Tool selection

By task

Decision rules

• Reading one property? Use node_get_property — cheaper than any tree walk.
• Surveying a tree? scene_get_tree defaults to max_depth: 2 (use -1 for the full tree, so you don't act on a truncated view). Prefer a filtered scene_query (offset/limit, default 50, clamped to 200) over scene_get_tree(include_properties: true) for surveys — paged reads carry a returned/has_more envelope; re-query from offset: 0 if the tree changed.
• Need a computed value or method call at runtime? Use execute_code. For a single property read, node_get_property is cheaper.
• Editor vs runtime diagnostics? editor_get_console for compilation errors and editor warnings; debugger_get_log for runtime crashes and game state.
• Control layout? control_set_layout sets an anchor preset plus optional margins in one call and returns the final rect.
• Exploring an unfamiliar node class? classdb_get_info (classdb group) returns every property, method, and signal with types. Follow with node_set_property to set what you find — covers any domain without memorising the API.
• Finding a class by capability? classdb_search({pattern: "collision", instantiable_only: true}). Narrow with base_class: "Node2D".

3. Workflow patterns

Scene creation -> test -> verify

1. scene_create — saves a new .tscn to disk; it does not open it
2. scene_open — make it the active scene (required before adding nodes)
3. scene_create_node for child nodes (batch siblings in one turn; inline properties supported — on partial failure the node is kept, check properties_failed)
4. script_write (new file) / script_edit (existing) → node_set_script
5. editor_save_scene to persist the mutations
6. game_start — returns runtime_ready: true when the runtime connects
7. discover_tools({request: "runtime"}) → runtime_get_node_state / input_simulate to verify

Dependency-aware build order. Create resources before scripts that reference them — "don't reference something that doesn't exist yet." Adapt to the project's dependency graph: utility scripts (no deps) → scenes (empty node trees) → scripts referencing scenes (use load(), runtime-evaluated) → autoloads via autoload_manage (not project_set_setting) → scripts referencing autoloads (by class_name).

Batch and parallelise scene construction

Two optimisations that compose: batch calls across siblings — all scene_create_node calls for one parent in a single turn (only serialise parent-child pairs); batch mode within a call — node_set_property with batch sets many properties on one or more nodes atomically. Independent read calls can also go out together in one turn (reads bypass the mutation queue; only order-dependent mutations need sequencing). Combined, scene setup drops from 30-40 sequential turns to 3-4 batched turns.

node_set_property({
  batch: [
    {node_path: "Player", property: "position", value: {type: "Vector2", x: 100, y: 200}},
    {node_path: "Enemy", property: "visible", value: false}
  ]
})

When batch is present, top-level property/value are ignored.

Autoload setup. Use autoload_manage to register autoloads — not project_set_setting (which rejects autoload/* keys and redirects). Register as early as possible so other scripts can reference them by class_name. After registering, call editor_refresh (editor_advanced group) to flush the editor cache: console errors that reference autoload singletons (e.g. "identifier not found") are usually stale cache — don't re-register or rewrite scripts until you've refreshed and re-checked.

Playtest verification loop

After game_start: verify key nodes exist with the right properties → input_simulate to send inputs (delay_after_ms 100-300ms) → verify state changed → repeat per scenario. Warning: delay_after_ms > 500ms is dangerous — the game world is live during delays, so enemies move and timers tick.

Verifying game state (cheapest to most expensive):

1. debugger_get_log — read print() output (available from startup; works during gameplay AND after a crash; limit / text_filter). Add strategic prints for key state (score, health, wave). Cheapest runtime check.
2. runtime_get_node_state (runtime_advanced group) — primarily @export vars and inspector-visible fields; put @export on key state vars.
3. runtime_get_script_vars — all script variables, not just exports (available from startup; visibility filter: public/private/all).
4. execute_code — arbitrary expressions on any node (available from startup; expression-only). Most flexible, larger responses than 1-3.
5. runtime_screenshot — visual check. Last resort, 5-10x the tokens of a text tool. Use image_detail: "low"/"mid" to save budget; on RUNTIME_WINDOW_MINIMIZED, retry with force_foreground_game: true.

Prefer 1-3; use 4 for computed values; use 5 only for visual layout, alignment, or rendering questions text tools can't answer.

Fast-forward testing with runtime_set_property

Instead of playing through the whole game, set late-game state directly. runtime_set_property (runtime_advanced group) supports compound paths (position:x). Example — test victory after wave 5:

runtime_set_property(node_path: "/root/GameManager", property: "current_wave", value: 5)
runtime_set_property(node_path: "/root/GameManager", property: "enemies_remaining", value: 0)

Then verify the victory screen triggers — skipping minutes of play and dozens of input_simulate calls.

Scene instantiation. scene_instantiate (scene_advanced group) auto-renames on name collision, so multiple instances of one scene work without manual renaming. Its instances: [{name?, position?, rotation?, scale?, properties?}] batch spawns N copies with transforms in one call.

Tilemap bulk fills. Use the regions parameter on tilemap_set_cells for large rectangular fills instead of listing cells one at a time (can be combined with cells). Read cells back with tilemap_read_cells (both in the tilemap group).

Script writing patterns

• Always add class_name — enables script-to-script references without load()/preload().
• @export for properties visible in the inspector and via runtime_get_node_state.
• Declare signals with typed parameters: signal health_changed(new_hp: int).
• @onready var label: Label = %ScoreLabel with unique-name nodes.
• Prefer script_edit for changes to an existing script — a surgical old_string -> new_string swap that keeps undo history and returns inline diagnostics. Use script_write for new files.
• Use script_write / script_edit for EVERY script file — including scratch drafts, experiments, and throwaway managers, never a native file-write tool. The MCP tools compile-check the code and register it with the running editor; a raw filesystem write does neither, so it is never the better choice in a live project.

Placeholder art. Use Godot primitives (ColorRect, Polygon2D, simple shapes) for placeholder visuals. For quick placeholder assets, texture_generate / sound_generate (placeholders group) exist — no external image tools needed.

Type wrappers for node_set_property

Engine types need a {type: ...} wrapper; plain numbers, strings, and booleans don't. The essentials — bind a resource, position, or colour:

• Resource: {type: "Resource", path: "res://texture.png"} (textures, audio, materials)
• Vector2: {type: "Vector2", x, y}
• Color: {type: "Color", r, g, b, a} (a defaults to 1.0)

Unknown type tags are rejected with the supported list. Full table — packed arrays, Transform2D/Transform3D, NewResource, NodePath, LayerMask, compound paths — in references/type-wrappers.md.

Signal workflow

• signal_manage — editor-time connect/disconnect (CONNECT_PERSIST — saved in .tscn, survives save/load; idempotent). Validates the signal exists on the source and the method on the target.
• signal_list — inspect signals and their connections (include_connections).
• signal_emit — fire a signal now: channel: "editor" (default, edited scene) or channel: "runtime" (the running game — needs the signals group activated and a running game).

Typical pattern: connect during setup with signal_manage -> game_start -> signal_emit(channel: "runtime") to trigger during testing. Cross-scene connections (source and target in different scenes) cannot persist — signal_manage returns a hint steering you to _ready() code instead.

Editor state management — refresh after external writes, save after mutations. editor_refresh (editor_advanced group) is for files created outside MCP tools (native Write/Bash) and after autoload registration (stale-cache errors); targeted file_paths is O(1) per file. editor_save_scene is not automatic — save after mutation batches before switching scenes or starting a playtest; saving flushes pending changes (no refresh-before-save needed).

input_simulate. Send a single event or an events array — prefer one call with multiple events. Keep delay_after_ms to 100-300ms; > 500ms is dangerous (the live game world advances during the wait). click_node (node_path, no coordinate guessing) and send_text (types into the focused / node_path field, firing real signals) exist. Coordinate modes: position (viewport/UI) vs world_position (game-world, camera-aware). Full event-type table in references/input-events.md.

4. Tool availability

A lean startup surface is small on purpose — large always-loaded tool lists degrade tool-selection accuracy in LLM contexts. Specialised tools live in on-demand groups you activate with discover_tools to reach the full surface.

Common groups — examples, not the full list:

Call discover_tools() with no arguments to see the full catalogue.

Version gating: on older Godot versions, version-gated tools are hidden from the tool list; a direct call fails with UNSUPPORTED, and the hint names the required version.

Extensions: projects can register their own MCP tools. They appear in discover_tools alongside the built-ins; extensions_refresh rescans after the extension files change.

Read-only mode. Set GODOT_MCP_READ_ONLY=1 in .mcp.json env (or use the dock's read-only toggle, which writes the env var for you). Only tools with readOnlyHint: true are visible — safe for exploration and auditing; the same annotation-driven filter applies to built-in and extension tools. To exit, turn it off and reconnect the client — the tool list is decided at connect time.

Context management: if on-demand groups accumulate and degrade tool selection, reset them — discover_tools({reset: true}) (all) or discover_tools({reset: ["tilemap", "audio"]}) (selective).

5. Headless mode

Launch: godot --headless --editor --path <project>

Build and validate normally: script_check, lsp_project_diagnostics, editor_get_console, and scene/node inspection all work. Run editor_refresh after external file writes (the filesystem scan is async headless).

Playtesting is unavailable headless — there is no display server for the game process, so game_start fails with HEADLESS_UNSUPPORTED, and editor_screenshot fails the same way. Verify via state queries and console output instead.

6. Key constraints

Never edit .tscn files directly. Always use the MCP scene tools (scene_create, scene_create_node, node_set_property). Direct .tscn edits bypass the editor's scene tree and cause silent data loss.

Root node path. The root node is always path "." — not the node name. Children are relative.

Runtime state visibility. runtime_get_node_state shows primarily @export vars and inspector-visible fields. Use execute_code for internal state.

Node method invocation. node_call_method is editor-side only. For methods on the running game use execute_code (its default channel is the running game): get_node('/root/Main/Player').call('take_damage', 25).

Stale live instance after a script edit (Godot < 4.4)

On Godot < 4.4 (4.2, 4.3), editing a .gd already attached to a live node does not reach that running instance: a newly-added method fails with INVALID_METHOD, and a changed method body runs the old code silently. editor_refresh, re-node_set_script, and a fresh node all keep the stale code — relaunch the editor (or disable+re-enable the plugin) before calling the changed members (script_write and node_call_method flag this in their hints). Best practice: write the full script before attaching it. On 4.4+ scripts hot-reload, so this doesn't apply.

Env var lifecycle. GODOT_MCP_* env vars (e.g. GODOT_MCP_READ_ONLY, GODOT_MCP_EDITOR_PORT) are read when the MCP server process starts. After editing .mcp.json, reconnect the MCP client — the tool list is decided at connect time, and a reconnect respawns the server with the fresh env.

GDScript pattern — prefer load() over preload(). Use class_name on every script for script-to-script references (no preload/load needed). Use load() for PackedScene instantiation and resource references — it evaluates at runtime and tolerates creation order. Never use preload() in generated code unless the target already exists and there are no circular dependencies.

GDScript pattern — use %UniqueName for node references. Mark frequently-referenced nodes with unique_name: true (via scene_create_node, or by setting unique_name_in_owner with node_set_property). Reference them as @onready var label: Label = %ScoreLabel — this survives reparenting. Use $ChildName only for structural direct children.

Console log sources. editor_get_console buffer mode captures all output on Godot 4.5+ (Logger API); it falls back to file-tail on 4.2-4.4 with ~200ms latency. Use source: "buffer" (default) for real-time capture.

Node groups. Use node_groups to add/remove/list groups — not node_set_property (groups are not a node property). Batch mode supports multiple nodes: node_groups(action: "add", entries: [{node_path: ".", group: "enemies"}, ...]).

File path conventions. Project files use res://; user:// data goes through the save tools (save_read / save_write / save_delete / save_list, user_data group) and screenshot save paths (user://screenshots/). Absolute OS paths and .. traversal are rejected by the file guard. scene_create and script_write auto-create parent directories; other tools may not — use folder_create for non-standard paths first.

7. Error recovery

Debug-first — when runtime behaviour is unexpected, always diagnose before retrying:

1. debugger_get_log — check what actually happened
2. Check delay_after_ms in input_simulate (>500ms lets the world advance)
3. Check game state via execute_code (still playing? player alive?)
4. THEN retry with adjusted parameters

This avoids misdiagnosis loops that waste thousands of tokens retrying when the root cause is elsewhere (e.g. input delays letting enemies kill the player before events process).

Common error codes

For deeper runtime diagnosis when logs aren't enough, activate the debugger group (debug_state, breakpoints, debug_continue).

8. Checkpoint pattern

For complex builds, commit progress at milestones. A standard order: project structure + main scene → game logic scripts → input handling → win/lose conditions → visual feedback → regular verification (game_start + runtime checks) → headless verification (if applicable).

If a session ends mid-task, record the current step and state so the next session can continue without re-reading the entire project.

9. Token efficiency

MCP tool calls are expensive — each round trip costs tokens for the request, the response, and the context it occupies:

• Batch properties instead of one-at-a-time: one node_set_property with batch replaces 5-10 individual calls.
• Activate groups in one call. Pass an array to discover_tools — every activation makes the client re-process the full tool list, so batch them.
• Use scene_get_tree sparingly. include_properties: true returns hundreds of lines even on a small scene; use node_get_property for targeted reads. Paged reads (scene_query, editor_get_console, debugger_get_log) carry a returned/has_more envelope.
• Read the console incrementally. editor_get_console supports since_id (page "what's new"), level_filter, and limit; debugger_get_log supports limit and text_filter.
• Keep node_get_property_list on mask="common" (default; the 8-12 most-edited properties) or use node_get_property — mask="all" is large.
• Never screenshot for debugging logic. debugger_get_log + runtime_get_node_state cost a fraction of a screenshot. Budget: image_detail: "low" for layout sanity, "mid" for most UI checks, "full" only to read small text; disk modes always persist full-res. Only use runtime_screenshot for visual layout, alignment, or rendering issues.
• Partial script reads. If you wrote the script, read only the function you need (start_line/end_line).
• Reset unused tool groups. Accumulated on-demand groups degrade tool selection — discover_tools({reset: true}) clears them.
• Diagnose before retrying. One debugger_get_log that reveals the root cause beats blindly retrying input_simulate five times.
• Use classdb_get_info with sections. All sections on a complex class returns thousands of lines — ask for ["properties"] or ["signals"] only.
• Use specific keys for project settings. project_get_settings(prefix: "display") returns hundreds of settings (including defaults); use a single key for one value. For a broad survey, Read(project.godot) is far cheaper — it holds only non-default settings. If the spec states the value, skip the read and set it directly.
• Follow the hint field on both errors and successes instead of re-querying or blindly retrying — it names the recovery step or the next tool.

10. Parallel sessions

Multiple sessions on one editor are safe — a mutation queue and a scene lease serialize conflicting work automatically; under contention responses get slower, not broken (a lease steal takes ~8s). If a response mentions another session editing a scene, do tab-independent work (scripts, files, project settings, autoloads, console reads) first. Full guide: references/parallel-sessions.md.

Gotcha quick-reference

These are the most common sources of wasted tool calls and retries: