Your first session

godot-mcp is driven through an AI assistant, not by typing tool names. So the single most useful thing you can do first is install the skill — a small bundle of knowledge your assistant loads automatically. It teaches it to:

• check the bridge and version before it starts,
• enable the toolset it needs, by itself (you never manage gates), and
• read the "what actually happened" fields and avoid the Godot pitfalls that trip agents up.

→ Install the skills (./scripts/install-skills.sh), then restart your assistant. From then on it just knows how to work in Godot.

With the skill in place you talk in plain language and supervise in Godot. The rhythm is always the same: orient → enable → preview → act → verify.

No skill installed?

The workflow degrades gracefully without it, but the assistant won't know to enable toolsets on its own or to read the honesty fields — you'll be prompting it about "unknown tool" errors and stale-save verdicts yourself. Install the skill.

1. Orient — ask who's connected

You: "Check that Godot is connected and tell me what's available."

The assistant confirms the editor is reachable and tells you what it can do. If it says the bridge isn't connected, open Godot with the addon enabled, check the status dock (bottom panel), and ask again — its report usually names the fix.

2. Enable what you need — the assistant handles it

Ask for anything that needs a gated toolset and the assistant turns it on itself — the part the getting-started skill teaches, so you don't have to think about it.

You: "Add a Player node to the main scene."

If your assistant instead stalls on an "unknown tool" error, it's missing the skill (or hasn't enabled the toolset) — prompt it: "enable the toolset you need first", or install the skill.

3. Inspect before mutating — the assistant reads, then edits

You: "What's in the scene right now?"

The assistant reads the scene tree, your current selection, and the project setup (autoloads, input actions, main scene). Node paths come back scene-relative (".", "Player/Weapon") in exactly the form the editing tools expect — and you can see the same thing live in Godot's Scene dock.

4. Preview, then act — you approve, the assistant mutates

You: "Create the Player node — preview it first."

Ask for a preview and the assistant shows what would happen, running the same checks the real run will — including whether a save would keep it — before anything changes. When it goes ahead, the change lands in your editor: watch it appear in the Scene dock, and press Ctrl+Z to undo it. Every assistant change is on the editor undo stack — as revertible as your own edits.

5. Verify — ask the assistant to prove it worked

You: "Check the script parses and the scene runs without errors."

A clean parse is not full verification — runtime mistakes only show up when the game actually runs. Ask for the verdict, not just the action: "does it run clean?" is a different question from "did you save it?"

Reading the results the assistant reports back

Under the hood

These fields are the server's honesty contract — what a save will really keep, what a batch actually ran, whether a check raced a rescan. See Persistence truth for how they're produced.

The assistant's results carry honesty fields that read as ground truth — check them (or ask the assistant to explain them):

• persisted: true → the save will keep the change.
• persisted: false, reason: instanced_child_not_editable → the edit shows in the editor but won't be saved; act on the hint (ask your assistant to enable Editable Children on the instanced scene, or to target a node the scene owns).
• rescan_pending: true on a parse check → the editor's file scan hadn't flushed; have the assistant re-check once before "fixing" correct code.
• aborted_at on a batch → trailing commands did not run.

A well-behaved assistant reads these and acts; ask it to when it doesn't.

When something fails

What you see	What it means	What to tell the assistant
"unknown tool"	the toolset isn't enabled	"enable the toolset first"
a "no scene open" precondition	nothing is open to edit	"open or create a scene"
a destructive action asks to confirm	it needs your OK first	review it, then "confirm and retry"
"Godot is not connected"	the editor isn't reachable	open Godot + addon; check the status dock
a typo'd key or path is rejected	a "did you mean…?" is offered	"use the suggested key"

The assistant's own report (and the troubleshoot prompt) usually names the fix.

Making it smoother

• Reach for prompts. The server's workflow prompts are step-numbered recipes the assistant can follow for a whole task — a skill points it at the right one.
• Start from an example. The two games under examples give the assistant a real project to work against.

Next: Build a scene walks the full loop, or Play-test & debug starts from the runtime side.