Breakpoint Mcp

A Model Context Protocol server that brings the Godot game engine into an AI assistant's development loop — authoring scenes, writing type-checked GDScript, running the project, and debugging the live game. Developed and tested with Claude; MCP is an open protocol, so other clients can connect too (see Compatibility).

npm 1.78.3 · addon 1.11.0 · full 292 / secure-default 279 tools · 6 MCP resources · MIT. The host builds against the stable @modelcontextprotocol/sdk 1.x API and is exercised by an 854-test suite plus real-Godot integration jobs on Node 18/20/22.

Breakpoint MCP connects an MCP-compatible AI assistant to a running Godot editor and game. Instead of only scaffolding files, the assistant can open a scene, add and wire nodes with full undo/redo, write GDScript with type-aware completion and diagnostics, set a breakpoint and step through a failure from real program state, and then drive the running game — the same inner loop a human developer uses.

It speaks Godot's own protocols — the editor plugin's loopback bridge, and Godot's built-in language server (LSP) and debug adapter (DAP) — rather than reimplementing them, so behavior tracks the engine you already have.

Why Breakpoint?

Breakpoint is an MCP server that drives Godot through the engine's own interfaces: the editor plugin's loopback bridge for scene/node/resource work, a runtime bridge inside the running game, the headless CLI, and — the part that sets it apart — Godot's built-in language server (LSP) and debug adapter (DAP), to which Breakpoint speaks as a real client. Most Godot MCP servers stop at the first group: they create and edit scenes and scripts, take screenshots, and read the output log. Several now add stepping too — but they drive Godot's internal editor debugger and present it in "DAP-style" shapes rather than speaking the Debug Adapter and language-server protocols as a client. Breakpoint is that client, for GDScript and C#, and its breakpoints are proven to stop execution by integration tests run against real Godot binaries in CI. That is the difference between observing a running game from the outside and stopping inside it at real program state.

Two differentiating capabilities are the reason to reach for Breakpoint:

• A step-debugger for GDScript and C#. Set a breakpoint, step, read the real call stack and variable values, watch expressions, and evaluate in the paused frame — over Godot's Debug Adapter (and netcoredbg for C#). This is the difference between inspecting state and reading logs: the assistant can stop at the failure and look at actual values instead of inferring them from print() output and re-runs. A runnable example lives in example/demo/: a buggy melting-snowman scene where the debugger stops on ice -= melt and reveals melt = -2 — a mild warm spell growing the ice instead of melting it. The same bug is mirrored in C# at example-csharp/demo/ (DemoSnowman.ApplyWarmth), diagnosed the same way over netcoredbg — and verified the same way on both tracks: the read-only assertion family below proves the one-line clamp over the runtime bridge (GrewEver == false, "ALL MELTED" on screen), a check that fails before the fix and passes after.
• A language-server client for GDScript and C#. Completion, hover, go-to-definition, find references, rename, and diagnostics — over Godot's LSP (and OmniSharp for C#). Edits are symbol-accurate rather than text-substituted, and type errors surface before the project runs.

Around those, the editing surface is built to be safe to hand to an agent: every edit goes through EditorUndoRedoManager (Ctrl-Z reverts anything the assistant did), destructive tools are confirmation-gated, and every tool result is validated against a frozen output schema. A read-only verification family (assert node state, scene structure, on-screen text, performance baselines, and screenshot diffs) lets the assistant check a running game the way a test would — and because the same server also debugs, a failed assertion is one step from the state that caused it. The editor, LSP, DAP, and runtime bridges are exercised together against a real headless Godot in CI.

It is also secure by default, which is unusual in this field — and the mechanism matters more than the label. A per-project shared secret authenticates every bridge (constant-time, minted into the git-ignored res://.godot/), every socket binds to loopback only, and the highest-blast tools — arbitrary code execution and network egress — are dropped at registration, not merely flagged. They are absent from tools/list until you opt in, so the default surface is 279 tools an agent can actually call, not 292 with a warning label on 13 of them. Destructive operations are confirmation-gated and fail closed on clients that cannot prompt. Nothing runs in the cloud and no project data leaves the machine.

Every tool also publishes MCP risk annotations (readOnlyHint / destructiveHint / idempotentHint / openWorldHint), and breakpoint-mcp tools --json exports the whole surface — so what the server can do, and how risky each tool is, is checkable without running it or guessing from tool names.

When Breakpoint is the right tool — and when it isn't

It earns its keep on work that needs program state or real symbols:

• Diagnosing a live failure — a wrong value, a null reference, a crash in a signal handler: breakpoint, step, and read the actual variables in the paused frame instead of instrumenting with prints and re-running.
• Refactoring against real symbols — rename a method or property project-wide, or find every reference, over the LSP, so it's accurate rather than a text search.
• Type-aware authoring — write GDScript or C# with completion and diagnostics, catching type errors before the game runs.
• C#/.NET projects — the LSP and DAP paths cover C# as well as GDScript.
• Verifying a running game in a loop — assert node/scene/screen/performance state after a change, with a failed assertion one step from the debugger.

If you only need scene and script edits from inside the editor — scaffolding a scene, generating a script from a prompt, quick one-shot changes — there are other good alternatives to Breakpoint available in the Godot Asset Library. Breakpoint's value shows up when you need to step through a bug, refactor against real symbols, or work in C#.

How it compares

The field has many capable Godot MCP servers, and it is growing quickly — most cluster on authoring. Breakpoint is deliberately different on the axes that need real program state, real symbols, and a surface that is safe to hand an agent by default:

Capability	A typical Godot MCP server	Breakpoint
Author scenes / scripts, screenshots, read logs	✅	✅
Step-debugger (breakpoints, stack, variables, watch)	Some — via Godot's internal editor debugger	✅ real DAP client; breakpoints proven to stop in CI
C# step-debugging	✗	✅ over netcoredbg
Language-server client (completion, rename, references)	Rare	✅ GDScript and C#
Runtime verification (assert node/scene/screen/perf, golden-image diff)	✗	✅ runtime_assert_* + runtime_screenshot_diff
Deterministic playtesting (freeze time, step exact frames, seed RNG, state digest)	✗	✅ frame-exact, verified on 4.3/4.5/4.7
Arbitrary code execution in the default surface	Usually present and callable	✅ absent — dropped at registration until opted in
Published risk annotations + machine-readable tool export	✗	✅ all 292 tools, CI-enforced
Undo-safe + schema-frozen results	Rare	✅ every mutation

This describes capability classes, not specific projects. Several servers are strong at authoring, some are actively adding debuggers, and if authoring is all you need there are good alternatives in the Asset Library. The tool count is not the axis — ours is 292 because that is what a static contract check asserts, and every one is schema-frozen and annotated.

What the tool surface costs, measured

Breadth is not free, and the honest way to offer it is to publish the bill. These are live measurements of what a tools/list response weighs — produced by host/scripts/token-cost.mjs against the running server, not estimates, and not figures quoted from anyone's README.

What an untouched install advertises is the secure-default surface of 279 tools; opting every higher-trust group in loads the full 292. Weighed:

	Bytes on the wire	≈ tokens	Bytes per tool
Breakpoint, as installed	343,463	~95,400	~1,231
Breakpoint, every group opted in	362,021	~100,600	~1,240
An authoring-focused server we re-measured	202,327	~56,200	~634

Two things are worth saying plainly. Per tool we are close to the field, and roughly half of our per-tool weight is something most servers do not send at all: a frozen outputSchema and a published risk annotation on every single tool, which is what lets a client validate a result and lets you audit the surface before you trust it.

And you almost never pay the full bill. Toolsets load only the planes you asked for, so a session that just needs the debugger pays for the debugger — a measured ~86–98% upfront reduction, and it is one environment variable:

BREAKPOINT_TOOLSETS=c        # the runtime plane alone
BREAKPOINT_TOOLSETS=a,b      # editor + CLI

The token figures are derived at ~3.6 bytes/token and are estimates; the byte counts are exact. Re-derive any row with node host/scripts/token-cost.mjs --summary, or point it at any other stdio MCP server with --server <cmd> and compare for yourself.

Why a Node host?

Breakpoint runs a small Node process on purpose: it is what lets the server act as a real LSP and DAP client (the two capabilities above), run long jobs on the MCP task model, and connect from any stdio MCP client. The host is the price of the debugger and the language server, not incidental plumbing. Setup is one command to install and one to verify:

npx breakpoint-mcp init     # copies + enables the addon and writes your MCP-client config
npx breakpoint-mcp doctor   # verifies the Godot binary and all four bridges are live
npx breakpoint-mcp --version  # the installed version — quote this in a bug report

If you never step through a bug or refactor against real symbols, you may not need the host; if you do, that is exactly what it buys.

What it does

Breakpoint MCP is organized into four capability planes (full 292 tools, or 279 with the privileged capability group off by default — see Safety & trust model — plus 6 resources):

• Plane A — Live Editor Bridge (toolset a → 148 tools: editor_*, scene_*, node_*, signal_*, resource_*, filesystem_*, anim_*, and more): a Godot EditorPlugin opens a loopback server the host drives for scene/node/resource CRUD with full undo/redo, project settings, ClassDB introspection, selection, main-screen tab control, and editor screenshots. A read-only documentation / code-lookup family (class_reference, docs_search) is part of that 148. Four sibling toolsets ride the same bridge and are counted separately — native multiplayer authoring (netcode → 7), backend-SDK integration scaffolding (backend → 5, including leaderboard_scaffold, cloudsave_scaffold and auth_scaffold), AI asset generation (assetgen → 7), and card/board/piece authoring (tabletop → 14) — so a,netcode,backend,assetgen,tabletop → 181 tools require the editor open, not the 148 alone.

• Plane B — Headless CLI & host-side tools (godot_*, vcs_*, project search): launch the editor, run the project, export, import, and run headless scripts or tests — no editor window required. Long-running jobs (godot_export, godot_import, godot_run_headless_script) run on the formal MCP task model (create → poll → await → cancel), while simpler clients still get a blocking result. godot_run_managed / godot_output capture the game's full console. Version control (vcs_*) reads the project's git repository (status, log, diff, show, branches, blame) and performs safe local git actions (stage, commit, restore, stash, branch, switch) — destructive ops are confirmation-gated, and no network operations are exposed (push/pull stay manual).

• Plane C — Runtime Bridge (runtime_*): an autoload (BreakpointRuntimeBridge) the plugin registers into every run opens a loopback server inside the running game — live SceneTree, runtime property get/set, method calls, signal emission, input injection for play-testing, performance monitors, and in-game frame capture — plus a read-only verification family (runtime_assert_* and runtime_screenshot_diff) for checking node state, scene structure, on-screen text, performance baselines, and screenshot diffs against a running game. On Godot 4.5+ it also captures the game's console (print(), warnings, errors) with zero configuration.

• Plane D — Semantic & Debugging (gd_*, dbg_*, plus C# cs_* / cs_dbg_*): the host connects as a client to Godot's built-in GDScript language server (port 6005) and debug adapter (port 6006) — completion, hover, definition/references, rename, symbols, signature help, diagnostics, plus real debugging: breakpoints, stepping, stack/scopes/variables, watch expressions, and expression evaluation. A parallel C# plane speaks OmniSharp (LSP) and netcoredbg (DAP). Capabilities are feature-detected per engine build and degrade to a clear "unsupported" message rather than erroring.

Six MCP resources (godot://scene-tree, godot://editor-state, godot://runtime/tree, godot://runtime/log, godot://class/{name}, and the always-on godot://capabilities) expose pull-on-demand context, and clients can subscribe to be pushed updates when the editor selection, edited scene, or the live SceneTree changes.

Highlights

• Undo-safe by construction. Every edit-time mutation is wrapped in EditorUndoRedoManager — Ctrl-Z reverts anything the assistant did.
• Confirmation-gated destructive tools. Anything that deletes, overwrites, or writes a file prompts for confirmation first (with a confirm: true override, and a safe block when the client can't prompt).
• Enforced output schemas. Tool results are validated against frozen output schemas.
• Local by design. All planes talk to 127.0.0.1; screenshots render real frames.

┌───────────────────── Claude (Code / Desktop) ─────────────────────┐
│                        MCP over stdio                              │
└─────────────────────────────┬──────────────────────────────────────┘
                      host/ (TypeScript MCP server)
   ┌────────────┬──────────────┬──────────────┬────────────┬───────────┐
 spawn CLI   TCP :9080      TCP :9081       TCP :6005    TCP :6006
 (headless)  editor addon   in-game         Godot LSP    Godot DAP
             scenes/nodes   autoload        completion,  breakpoints,
             /undo          live SceneTree  diagnostics  stepping, eval
                            /monitors/input

Requirements

• Node ≥ 18 (for the host).
• Godot 4.2+ for the editor addon (4.4+ recommended). A few runtime features use Godot 4.5+, and some language-server / debug-adapter capabilities light up on newer builds as the engine implements them.

Installation

Quick start (recommended)

From your Godot project folder, one command installs and enables the editor addon and prints your MCP-client config:

npx breakpoint-mcp init

Then open the project in Godot and verify everything is wired up:

npx breakpoint-mcp doctor

If the project was already open in Godot when you ran init, reopen it. init enables the plugin by writing [editor_plugins] into project.godot, and Godot reads that file at project load — it does not hot-reload it. An editor that was already running keeps the plugin disabled, the editor bridge never starts, and doctor --require-live reports it as down. Closing the project and opening it again is the fix.

init copies the addon into addons/breakpoint_mcp/, enables it in project.godot, and prints the client config snippet — pass --client claude-desktop|cursor|windsurf|vscode to write it into that client's config directly, or --client claude-code to get the claude mcp add command. By default init installs the addon bundled in the package; add --from-github [ref] to fetch it from GitHub instead (e.g. --from-github main for the latest, or a tag like --from-github v1.3.0; --repo <owner/repo> targets a fork). doctor checks the Godot binary, the addon, and the four bridges (add --require-live once the editor is open to require the three the editor brings up, or --require-live=all to also require the runtime bridge, which only exists while the game is running; --json for a machine-readable report). The manual steps below do the same thing by hand.

1. Install the editor addon (manual)

These by-hand steps are for working from a checkout of this repository, or if you would rather do it yourself. If you installed from npm, npx breakpoint-mcp init does all of this for you — the addon ships bundled in the package, so you don't need the repository.

Copy addons/breakpoint_mcp/ into your project's addons/ folder, then enable it under Project → Project Settings → Plugins → Breakpoint MCP. On enable it listens on 127.0.0.1:9080 (override with BREAKPOINT_BRIDGE_PORT before launching Godot).

Enabling the plugin also auto-registers the runtime autoload (BreakpointRuntimeBridge), so the runtime_* tools work as soon as the project runs (it listens on 127.0.0.1:9081 inside the game). No manual autoload setup needed.

Once enabled, a Breakpoint MCP dock appears on the right-hand side of the editor. It shows the live health of all four bridges (editor / runtime / GDScript LSP / DAP), the configured ports and project path, and a one-click Copy MCP-client config button — the in-editor twin of doctor + init. It is status/config only: the assistant still runs in your MCP client, not in the editor.

Godot's language server (port 6005) and debug adapter (port 6006) are built in and enabled by default while the editor is open — the gd_* and dbg_* tools use them directly, no addon required. Ports are configurable under Editor → Editor Settings → Network → Language Server / Debug Adapter.

2. Get the host

The host is published to npm as breakpoint-mcp:

npx breakpoint-mcp        # run on demand
# or
npm i -g breakpoint-mcp   # install the `breakpoint-mcp` command

To build from source instead:

cd host
npm install
npm run build   # tsc -> dist/

3. Register with your MCP client

Claude is the primary, tested client. Claude Code:

claude mcp add godot -- npx -y breakpoint-mcp

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "breakpoint-mcp"],
      "env": {
        "GODOT_BIN": "/abs/path/to/Godot",
        "GODOT_PROJECT": "/abs/path/to/your/project"
      }
    }
  }
}

Using a different MCP client (Cursor, VS Code, Windsurf, etc.)? See Compatibility below — the command is the same, only the config file and wrapper key differ.

Configuration (environment variables)

Var	Default	Meaning
GODOT_BIN	godot	Path to the Godot editor binary
GODOT_PROJECT	cwd	Project directory (contains project.godot)
BREAKPOINT_BRIDGE_HOST	127.0.0.1	Editor-bridge host
BREAKPOINT_BRIDGE_PORT	9080	Editor-bridge port (must match the addon)
BREAKPOINT_BRIDGE_TIMEOUT_MS	15000	Per-request timeout for editor tools
GODOT_LSP_HOST / GODOT_LSP_PORT	127.0.0.1 / 6005	GDScript language server
GODOT_DAP_HOST / GODOT_DAP_PORT	127.0.0.1 / 6006	Debug adapter
GODOT_LSP_TIMEOUT_MS / GODOT_DAP_TIMEOUT_MS	15000 / 20000	LSP / DAP timeouts
BREAKPOINT_RUNTIME_HOST / BREAKPOINT_RUNTIME_PORT	127.0.0.1 / 9081	In-game runtime bridge (must match the autoload)
BREAKPOINT_RUNTIME_TIMEOUT_MS	15000	Runtime request timeout
BREAKPOINT_TOOLSETS	(unset → all)	Comma/space list of tool groups or planes to enable — see Toolsets
BREAKPOINT_PRIVILEGED_GROUPS	(unset → none)	Comma/space list of the default-OFF capability groups to enable: code-execution, or all. Off → secure-default 279 tools; opting in loads the full 292 — see Safety & trust model

Renamed from CLAUDE_*: the BREAKPOINT_* variables above (plus BREAKPOINT_RESOURCE_COALESCE_MS) were named CLAUDE_* in earlier versions. The legacy CLAUDE_* names were honoured with a one-time deprecation warning in 1.0.0 and removed in 1.1.0 — use the BREAKPOINT_* names. GODOT_* variables are unchanged.

The full, annotated configuration reference is in the User Guide.

Toolsets (optional — load only the planes you need)

By default the server registers the full surface (292 tools). On Claude Code that costs nothing at decision time: Tool Search defers the catalog and loads each schema on demand (a measured ~86–98% upfront token reduction — the model never sees all 292 at once). For clients that can't defer tools, or when you just want a smaller default menu, set BREAKPOINT_TOOLSETS to a comma- or space-separated list of groups; only those register. The four planes already are the grouping, so the aliases mirror them:

Token	Enables
a	Plane A — live editor authoring (editor)
b	Plane B — headless CLI (cli)
c	Plane C — running-game runtime + verification family (runtime)
d	Plane D — GDScript & C# LSP/DAP (lsp,cslsp,dap,csdap)
csharp	The C# language-server + debugger groups (cslsp,csdap)
all	The full surface (the default)

…or any of the concrete group ids: cli editor lsp cslsp dap csdap runtime processes knowledge vcs assetgen netcode backend tabletop resources.

Examples: BREAKPOINT_TOOLSETS=c → 27 runtime tools; a,b → 155 (editor + CLI); editor,runtime,vcs → 187. Unknown tokens are ignored, and a filter that resolves to nothing falls back to the full surface — a typo never yields an empty server. This is a menu filter, not a capability cut: every tool that loads is the same typed, schema-validated, undoable tool it always was.

Recipes (free, curated task workflows)

Breakpoint ships 8 recipes — short, opinionated workflows that drive its own enforced tools to accomplish a common Godot task and then verify it. They're exposed as standard MCP prompts (discoverable via prompts/list), so a client can pull one on demand:

• recipe_2d_player_controller — a movable CharacterBody2D with input actions + camera, then a runtime check that it actually moved.
• recipe_wire_signal_and_assert — connect a signal and prove at runtime the handler fired.
• recipe_debug_inspect_variable — set a breakpoint, launch under the debugger, read real call-stack values.
• recipe_screenshot_regression — golden-image check for a scene via runtime_screenshot_diff.
• recipe_type_safe_edit — edit GDScript with the language server (symbols, references, diagnostics) before running.
• recipe_csharp_fix_and_debug — the same inspect → fix → debug loop for C# via OmniSharp + netcoredbg.
• recipe_deterministic_playtest — freeze the game, step an exact number of frames, then assert a frame-exact state and a golden frame.
• recipe_multiplayer_scaffold_and_converge — scaffold netcode with the mp_* family, then spawn real headless peers and prove they converge.

Recipes are skills which ride on top of typed, schema-validated, undoable tools — so the contract is executed by the server, not merely described in prose which a model might misapply. Recipes also add no tools (the count stays 292) and cost nothing until pulled.

Recipes are the extension point — and the open hatch is a deliberate decline

A recipe composes tools that already exist; it never adds one. That distinction is what keeps this server's claims intact rather than nominal. Every tool here is typed, schema-frozen, contract-checked, risk-annotated and capability-gated, and a recipe inherits all five for free, because a recipe is a saved prompt over tools the caller could have typed by hand. It is strictly less privileged than the agent driving it: it cannot bypass the confirmation gate, cannot reach a tool that a disabled capability group dropped, and cannot add a name to tools/list.

A "bring-your-own-tool" API — a config file or plugin that injects a new tool at runtime — is therefore a deliberate decline, not a gap we haven't got to yet. An injected tool has no frozen output schema, no catalog entry, no annotation and no capability tag, and scripts/contract_check.py cannot parse it to check for any of those. The gates would not be weakened so much as rendered inapplicable, silently, for exactly the tools least likely to deserve the benefit of the doubt.

So the extension story is the recipe shape and nothing wider. Today that means the curated set above; loading user-authored recipes from a project directory is the one narrowing we would build if people ask for it, and it would still add no tools. If you need a workflow Breakpoint doesn't ship, open an issue — that path costs you nothing and costs the trust model nothing.

Compatibility

Breakpoint MCP is a standard MCP server that talks over stdio, so in principle it works with any MCP-compatible client. It is developed and tested with Claude (Claude Code and Claude Desktop) — that's the supported path today. Other clients such as Cursor, VS Code (Copilot agent mode), and Windsurf should work with the same command and environment variables, but they are not yet tested with this server. If you try Breakpoint MCP with another client — or a different model behind it — we'd genuinely love to hear how it goes: please open an issue describing your client and what worked or didn't.

Every client launches the host the same way: the command npx -y breakpoint-mcp with the environment variables from the table above. Only the config file location and the wrapper key differ.

Client	Config file	Wrapper key	Notes
Claude Code	—	—	claude mcp add godot -- npx -y breakpoint-mcp
Claude Desktop	claude_desktop_config.json	mcpServers	see example above
Cursor	~/.cursor/mcp.json (global) or .cursor/mcp.json (project)	mcpServers	same shape as Claude Desktop
VS Code (Copilot agent mode)	.vscode/mcp.json	servers	each entry also needs "type": "stdio"
Windsurf (Cascade)	~/.codeium/windsurf/mcp_config.json	mcpServers	same shape as Claude Desktop
Any other MCP client	per its docs	—	point it at npx -y breakpoint-mcp as a stdio server + pass the env vars

VS Code uses a slightly different shape (servers, with an explicit transport type):

{
  "servers": {
    "godot": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "breakpoint-mcp"],
      "env": {
        "GODOT_BIN": "/abs/path/to/Godot",
        "GODOT_PROJECT": "/abs/path/to/your/project"
      }
    }
  }
}

Because the tool descriptions were tuned with Claude, another model may drive the tools differently; if you notice rough edges with a particular client or model, an issue with details helps us improve the experience for everyone.

A typical session

1. godot_launch_editor (or open the project yourself).
2. editor_ping → confirm the bridge is live.
3. scene_get_tree, classdb_get_class → understand the scene and API.
4. node_add, node_set_property, … → make changes (all undoable).
5. gd_completion / gd_diagnostics → write GDScript with type awareness and catch errors before running.
6. main_screen_set → screenshot_editor → let Claude see the result. The tab has to match the viewport you want; a fresh editor is on 3D and opening a scene does not switch it.
7. dbg_set_breakpoints → dbg_launch → dbg_stack_trace / dbg_variables / dbg_evaluate → debug from real program state.
8. godot_run_project — which waits for the game's runtime bridge and says so with bridge_ready, rather than answering while the game is still booting — then runtime_get_tree / runtime_set_property / runtime_inject_input / runtime_screenshot → drive and observe the running game.
9. godot_run_headless_script → run tests.

The User Guide walks through this end to end.

Safety & trust model

Breakpoint MCP is a local co-development tool and is built to keep you in control:

• Every edit-time mutation goes through EditorUndoRedoManager — Ctrl-Z reverts anything the assistant did — and through the editor API (preserving UIDs/refs), never raw file writes.
• All sockets bind to loopback (127.0.0.1) only; handlers run on the editor main thread, so there are no threading hazards.
• Both bridges require a per-project shared secret (default-on since 1.17.0). The addon mints a 64-char hex secret into the engine-managed, git-ignored res://.godot/, and the host authenticates as the first frame on connect — so another local process on a shared machine can neither drive the bridge nor bypass the confirmation gate. The secret is compared in constant time and a bad handshake is refused without echoing it. Opt out with BREAKPOINT_BRIDGE_INSECURE=1.
• Destructive tools are elicitation-gated: the host asks the client to confirm before executing (for example node_delete, project_set_setting, scene_new, gd_rename with apply, the file/resource/script writers, and the runtime_* mutators). Pass confirm: true to auto-approve; if the client can't prompt, the tool blocks rather than acting silently.
• Least-privilege by default — capability groups (since 1.18.0). The higher-blast tools are gathered into one default-OFF group: code-execution (runs GDScript, invokes arbitrary methods, evaluates in a paused frame, or spawns the local asset-gen command backend). With it off, those tools are dropped at registration and never appear in tools/list, so the secure-default surface is 279 tools; opt in with BREAKPOINT_PRIVILEGED_GROUPS=code-execution (or all, or breakpoint-mcp init --trust full) to load the full 292. There is deliberately no network group — nothing on this surface egresses beyond loopback, and openWorldHint is false for every tool. A group named for egress that gated two loopback-only tools misstated the risk in both directions, so it was removed rather than left unused (1.28.0). The always-on godot://capabilities resource lists every group, its state, and the exact tools it gates, so a disabled tool is discoverable rather than a silent gap. Defense-in-depth and a legible least-privilege story over an already typed / undoable / gated surface — not the closing of an open hole.
• Pause the agent on demand — two layered controls. In the editor, the Breakpoint status dock has a "Pause Agent" toggle: while engaged, the editor and runtime bridges reject new commands on those two planes (an op already running finishes; a bare liveness ping still answers), so one click freezes what the assistant can do to your project and the running game. Headless or scripted, the host also honors SIGUSR1 (pause) / SIGUSR2 (resume) — a finer latch that holds only mutating actions but across the whole tool surface, with BREAKPOINT_START_PAUSED=1 to start held. Neither is an "emergency stop": both hold entry to a new action and never interrupt one already in flight, and the per-tool confirmation above stays the primary control for destructive ops.
• Higher-trust surfaces, stated plainly: godot_run_headless_script and godot_run_managed execute GDScript, and the optional asset-gen command backend runs a local command you configure (via BREAKPOINT_ASSETGEN_CMD or the tool argument). These sit in the default-OFF code-execution group above and stay elicitation-gated even once enabled — point them only at code you trust.

Security policy and how to report a vulnerability: see SECURITY.md.

What the automation actually verifies (W/R/E)

Breakpoint is explicit about what kind of evidence a result carries, using a three-tier honesty vocabulary:

Tier	Question	Evidence Breakpoint produces	Who asserts
W — Wired	Did the action actually happen?	Schema-frozen results, reversible via EditorUndoRedoManager	Automation
R — Runtime	Does the running program behave?	Live assertions (runtime_assert_*), runtime_screenshot_diff, and a real DAP paused stack + variable values (GDScript and C#)	Automation
E — Experience	Is it any good — fun, legible, the right feel?	Human perception; automation hands over evidence and leaves the verdict open	Human only

Most of the field proves R with a screenshot or a console line; Breakpoint proves it with an assertion, a diff, and a paused stack frame — and never lets automation claim E.

Documentation

• User Guide — the full manual: install, configure, concepts, workflows, troubleshooting, and FAQ.
• Tool Catalog — every tool with its input and output JSON Schemas.
• Runbook — step-by-step live-validation checklist.
• Changelog — release history.
• Contributing · Security · Code of Conduct

Development

# static checks (no Godot or registry needed for the parity check)
python3 scripts/contract_check.py                 # host <-> addon <-> catalog agree
cd host && npm ci && npm run build && npm run typecheck && npm test

CI runs the real build and test suite on Node 18/20/22 plus the parity check, and exercises the CLI, runtime, C#, and editor/debug planes against a real Godot engine. See CONTRIBUTING.md to get set up.

SDK note: the host targets the stable @modelcontextprotocol/sdk 1.x high-level API (server.registerTool(name, { title, description, inputSchema }, handler)). If you prefer the newer SDK v2 surface, adjust the import lines and wrap each inputSchema in z.object(...); the tool logic is unchanged.

Trademarks

Godot and the Godot logo are trademarks of the Godot Foundation. Claude and Anthropic are trademarks of Anthropic, PBC. SilentWolf, Nakama (Heroic Labs), PlayFab (Microsoft), and Photon (Exit Games) are trademarks of their respective owners. Breakpoint MCP is an independent, community-built project and is not affiliated with, sponsored by, or endorsed by any of them; their names are used only to describe interoperability.

License

MIT — see LICENSE.