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 ; MCP is an open protocol, so other clients can
connect too (see ).
MCP server exposing Godot to AI coding assistants over the Model Context Protocol — developed and tested with Claude — across four planes (CLI, live editor, LSP+DAP, runtime) with elicitation-gated destructive tools, long jobs on the formal MCP task model
npm 1.87.0 · addon 1.17.0 · full 293 / secure-default 280 tools · 6 MCP resources · MIT. The host builds against
the stable @modelcontextprotocol/sdk 1.x API and is exercised by a 1000-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 280 tools an agent can actually call, not 293 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:
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 293 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 293 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 280 tools; opting every
higher-trust group in loads the full 293. Two numbers per row, because they are different bills:
what the client downloads (tools/list on the wire), and what the model reads — a client
hands Claude each tool's name, description and input schema and nothing else.
Bytes on the wire
What the model reads
Breakpoint, as installed (280 tools)
353,591
208,700
Breakpoint, every group opted in (293 tools)
373,677
221,780
An authoring-focused server we re-measured (319 tools)
202,327
196,585
The second column is measured, not assumed: we captured the request Claude Code 2.1.201 actually
builds with Breakpoint attached (pointed at a local capture server; nothing was sent anywhere).
Every one of the 280 tools arrived as name, description and input schema — no output schema, no
risk annotation, no title. So the weight that sets Breakpoint apart on the wire — a frozen
outputSchema and a published risk annotation on every tool, which is what lets a client validate
a result and lets you audit the surface before you trust it — costs the model's context nothing.
Per tool, what Claude reads is about 1.2× the leanest alternative we have measured.
In Claude Code, the upfront bill is smaller still. Its default MCP tool search sends only tool
names until the model asks for a tool, so a session pays roughly 10 KB for the whole surface and
about three-quarters of a kilobyte for each tool it actually loads. The full model-read column is what a client without tool
search pays upfront.
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:
The byte counts are exact (≈ tokens at ~3.6 bytes/token, an estimate). Re-derive any row with
node host/scripts/token-cost.mjs --summary — it prints both columns — 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 293 tools, or 280 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.
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. The
autoload ships in your exports too, and there it stays closed: only a game started by an
editor build opens the port (details).
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:
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 280 tools; opting in loads the full 293 — 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 (293 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 293 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 → 156 (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.
Tool limits — if your client refuses to load Breakpoint
Some clients cap how many tools a server may advertise and refuse the whole server past
that cap. The refusal happens before any Breakpoint code runs, so there is no Breakpoint log
to read and nothing in this repository the symptom obviously points at — which is why the
exact text is quoted here, to be searchable:
Client
Cap
What you see
Google Antigravity
100
enabled tools would exceed max limit of 100, and the server does not load at all
VS Code (agent mode)
128
agent mode is blocked once the total across every enabled server goes over
The default surface is larger than both, so on a capped client pick a preset that fits.
These two are published and measured — host/test/client_caps.test.ts counts each one
against the smallest cap above on every run, so a tool added later reddens a test here
instead of an editor there:
Preset
Size
What you keep
BREAKPOINT_TOOLSETS=d
→ 58
Plane D whole: GDScript and C# language servers, GDScript and C# debuggers — breakpoints, stepping, stack frames, scopes, watch expressions, variable writes
BREAKPOINT_TOOLSETS=b,c,d
→ 93
The above plus the headless CLI (Plane B) and the running-game runtime and verification family (Plane C) — everything except live editor authoring
Both fit under every cap in the table. d is the debugging-first preset and the one the
startup line recommends; b,c,d is the largest published preset that still fits, so it has
the least headroom as the surface grows.
Every run also prints what it actually registered, on stderr, at startup:
[breakpoint-mcp] tool surface: 280 tool(s) registered · groups assetgen,backend,cli,…
That line is the count your client is being offered — after the toolset filter and after the
default-off capability groups are dropped — and it names the remedy whenever it is over the
smallest cap. A configuration you can read is a configuration you can fix.
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 293) 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):
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
godot_launch_editor (or open the project yourself).
editor_ping → confirm the bridge is live.
scene_get_tree, classdb_get_class → understand the scene and API.
node_add, node_set_property, … → make changes (all undoable).
gd_completion / gd_diagnostics → write GDScript with type awareness and catch
errors before running.
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.
dbg_set_breakpoints → dbg_launch → dbg_stack_trace / dbg_variables /
dbg_evaluate → debug from real program state.
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.
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 280 tools; opt in with
BREAKPOINT_PRIVILEGED_GROUPS=code-execution (or all, or
breakpoint-mcp init --trust full) to load the full 293. 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.
# 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/sdk1.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.
MCP server exposing Godot to AI coding assistants over the Model Context Protocol — developed and tested with Claude — across four planes (CLI, live editor, LSP+DAP, runtime) with elicitation-gated de
MCP server exposing Godot to AI coding assistants over the Model Context Protocol — developed and tested with Claude — across four planes (CLI, live editor, LSP+DAP, runtime) with elicitation-gated destructive tools, long jobs on the formal MCP task model
上次检查时间:2026-11-15。 MCP server exposing Godot to AI coding assistants over the Model Context Protocol — developed and tested with Claude — across four planes (CLI, live editor, LSP+DAP, runtime) with elicitation-gated destructive tools, long jobs on the formal MCP task model