godot-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@godot-mcpShow me a runtime snapshot of the active scene."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
godot-dev-mcp
This repository is archived and no longer maintained. The project was superseded bySwallowtail, which provides the adopted Godot CLI, Editor, runtime automation, testing, and MCP workflow. This code remains available for historical reference only.
Safe, composable MCP (Model Context Protocol) gateway for Godot: scene authoring, read-only runtime diagnostics, and allowlisted verification.
Current version is 0.2.0. Python 3.11+ is required.
Contents
Related MCP server: godot-ai-mcp
What it is
godot-dev-mcp lets MCP clients such as Codex inspect and change Godot projects with structured tools, instead of guessing .tscn formats or running arbitrary commands.
You can | It will not |
Inspect scenes, nodes, resources, signals, and scripts | Run arbitrary shell commands |
Preview a single scene-property change with dry-run | Read arbitrary files or write at runtime |
Read the Editor or game scene tree, logs, screenshots, and performance | Expose the observation bridge off loopback |
Run allowlisted tests and Stagehand scenarios | Bind a specific game project into the generic core |
The MCP server uses standard stdio transport: one UTF-8 JSON-RPC message per line. It supports requests, notifications, and batches, and never writes non-protocol content to stdout.
Architecture
flowchart LR
Client["MCP Client<br/>Codex / Claude"] -->|stdio JSON-RPC| Server["godot-dev-mcp<br/>Python 3.11+"]
Server -->|"AUTHOR: inspect / dry-run patch"| Project["Godot project<br/>.tscn .gd .tres"]
Server -->|"OBSERVE: HTTP GET loopback"| Editor["Editor Observer<br/>127.0.0.1:7331"]
Server -->|"OBSERVE: HTTP GET loopback"| Runtime["Runtime Observer<br/>127.0.0.1:7332"]
Server -->|"VERIFY: allowlisted argv"| Checks["project checks<br/>Stagehand adapter"]
Addon["addons/godot_dev_mcp"] --> Editor
Addon --> RuntimeCapability boundaries
Layer | Purpose | Write behavior |
AUTHOR | Inspect scenes, nodes, resources, signals, and scripts, and patch a single scene property | Mutations default to dry-run; writes only when dry-run is explicitly disabled |
OBSERVE | Read the Editor or game scene tree, node properties, performance, logs, and screenshots | Read-only; loopback HTTP GET only |
VERIFY | Run allowlisted test commands and parse Stagehand, JUnit, and visual-diff output | Runs explicit argument arrays only; never through a shell |
Quick start
1. Install the Python package
git clone https://github.com/DLeungDL/godot-dev-mcp.git
Set-Location godot-dev-mcp
python -m pip install -e .
python -m unittest discover -s tests -v2. Enable the Godot addon
Copy addons/godot_dev_mcp from this repository into the target Godot project's addons/ folder. In Godot, open Project Settings → Plugins and enable godot-dev-mcp Observer.
Enabling the addon also registers the GodotDevMCPRuntimeObserver autoload. Restart the Godot Editor after the first install or an addon update so Observer loads in normal editor sessions.
3. Start the MCP server
To inspect the scene tree in the Godot Editor, use the default Editor Observer:
python -m godot_dev_mcp.server --project "C:\path\to\godot-project"To inspect a running game, start the game from Godot first, then connect Runtime Observer:
python -m godot_dev_mcp.server `
--project "C:\path\to\godot-project" `
--bridge-url "http://127.0.0.1:7332"4. Connect Codex
[mcp_servers.godot_dev]
command = "python"
args = ["-m", "godot_dev_mcp.server", "--project", "C:\\path\\to\\godot-project"]
cwd = "C:\\path\\to\\godot-dev-mcp"To connect a running game, change args to:
args = [
"-m", "godot_dev_mcp.server",
"--project", "C:\\path\\to\\godot-project",
"--bridge-url", "http://127.0.0.1:7332"
]Observer connections
Observer | Default URL | Scope |
Editor Observer |
| Godot Editor scene tree |
Runtime Observer |
| Running game scene tree |
Quick health checks:
Invoke-RestMethod http://127.0.0.1:7331/health
Invoke-RestMethod http://127.0.0.1:7332/healthRuntime Observer starts in debug builds only. To enable it in a release build, set:
godot_dev_mcp/allow_release_observer=trueChange the runtime port with godot_dev_mcp/runtime_port. If you change the port, the MCP server --bridge-url must match.
Runtime Observer uses a custom Godot Logger to capture engine messages, push_warning(), push_error(), script errors, and shader errors. Logger callbacks enqueue work under a Mutex; the main thread then writes a ring buffer of at most 500 entries. Screenshots need a display server; headless mode returns 503 Service Unavailable.
Tools
Layer | Tools |
AUTHOR |
|
OBSERVE |
|
VERIFY |
|
godot_scene_patch defaults dry_run to true. A write happens only when you pass false, and only for a single .tscn property. Node selectors accept a name, relative path, or full scene path; ambiguous names are rejected. Replacing an existing multiline property removes the full old value. The result includes the resolved scene_path plus a before/after change summary.
godot_scene_inspect returns bounded structured_nodes with node name, type, parent, scene path, and up to 100 properties. Multiline properties keep their full serialized form. Each value is capped at 4,096 characters, each node at 32,768 characters, and the whole scene at 131,072 characters. Truncated items are listed in truncated_properties. Pass an optional node selector to get an exact selected_node by name or scene path; use the full path when the name is not unique.
godot_runtime_snapshot returns a depth-first flat nodes page with pagination:
Default
limit=100, maximum500Use
next_offsetfor the next pagemax_depthmaximum is16offsetmaximum is100000
Project config and VERIFY
Copy examples/godot-dev-mcp.example.json to godot-dev-mcp.json at the target project root, then edit it for that project.
{
"checks": {
"smoke": ["godot", "--headless", "--path", ".", "--quit-after", "60"]
},
"stagehand": {
"command": ["godot-stagehand", "run", "--out-dir", "stagehand-artifacts"],
"junit": "stagehand-artifacts/junit.xml",
"report": "stagehand-artifacts/report.json",
"visual_diff": "stagehand-artifacts/visual-diff.json"
}
}Check names are the allowlist accepted by
godot_run_check.Commands must be non-empty string arrays and start with
shell=false.Timeouts are 1–900 seconds.
Stagehand stays a separate adapter; this project only passes a scenario and parses structured artifacts.
A Stagehand scenario example is in
examples/auction-ui.stagehand.json.
Verification status
CI in this repository runs:
Python unit tests and MCP stdio subprocess integration tests
Python
compileallplus wheel/sdist packagingGodot 4.7.1 Mono headless Editor addon load
Runtime Observer has also been checked against the official 2d/dodge_the_creeps demo: it can read a real game scene tree, performance monitors, and structured runtime errors.
The version 2 integration roadmap is in Issue #1.
Safety boundaries
Project paths are resolved and path traversal is rejected.
The observation bridge must use HTTP loopback.
Runtime properties are limited to engine properties; script-defined properties are not exposed.
Lists, process output, tree depth, snapshot pages, and log buffers are all bounded.
There is no arbitrary shell command, arbitrary file-read, or runtime write interface.
Project-specific extensions are off by default; the generic core does not depend on game-specific code.
License and sources
This project is MIT licensed and is a clean-room implementation. Interface review and attribution for external projects are in THIRD_PARTY_NOTICES.md.
Available Tools
15 toolsgodot_project_infoC
Inspect the configured Godot project.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full behavioral burden. “Inspect” implies a read operation, but the description does not disclose permissions, side effects, return contents, or whether any project configuration is affected. It provides almost no behavioral context beyond the verb.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The definition is a single short sentence with no wasted clauses and is front-loaded with the core action. Its brevity is appropriate structurally, though the content itself remains thin.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations and no output schema, the description must explain enough for an agent to know what project information will be returned. It does not describe whether the result contains paths, settings, version data, or editor state, leaving the tool's utility ambiguous. This is insufficient for confident selection among many sibling inspection tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there are no parameter semantics to explain. The baseline score of 4 applies because the description does not need to compensate for an input schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a clear verb and resource: inspecting the configured Godot project. However, “inspect” is broad and does not state what project information is returned or how this differs from sibling inspection tools such as godot_scene_inspect or godot_resource_inspect. It is understandable but vague about scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no when-to-use guidance, no exclusions, and no alternatives. It does not explain whether this tool should be used before scene/resource inspection or what conditions make it appropriate. Usage must be inferred entirely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
godot_resource_inspectC
Inspect a project resource without modifying it.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It does disclose that the operation does not modify the resource, but it says nothing about permissions, supported resource types, failure modes, or what information is returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The single sentence is front-loaded and contains no wasted words. However, it is under-specified rather than appropriately concise for a tool that must be selected correctly among many siblings.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a simple schema and no output schema, but an inspection tool should still state what it returns, what resource types it handles, and how to interpret the path. None of that is present, leaving key usage context missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is one required parameter, path, and schema description coverage is 0%. The description does not explain whether the path is a res:// path, a filesystem path, or which resource types are accepted, so the parameter remains ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb-resource pair: inspect a project resource. It also clarifies the operation is non-modifying. However, it does not distinguish this tool from nearby siblings such as godot_scene_inspect or godot_resource_leaks, so an agent must infer the boundary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives like godot_scene_inspect, godot_project_info, or godot_resource_leaks. There are no stated preconditions, exclusions, or routing cues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
godot_resource_leaksB
Find RID, ObjectDB, and resource teardown warnings.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden, yet it says nothing about whether the engine/editor must be live, whether it reads accumulated logs versus probing current state, or whether results are per-run. Only the word "Find" weakly implies a read-only, non-destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence with the diagnostic target front-loaded and no filler. Nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no output schema and no annotations, the description should at least say what comes back and what state the project must be in. It identifies the subject matter well but leaves the agent guessing about invocation context and result shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is no parameter semantics to explain; the baseline of 4 applies. The description neither helps nor harms here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ("Find") and a concrete resource ("RID, ObjectDB, and resource teardown warnings"), which is a recognizable Godot leak-diagnostic category. It is distinguishable from godot_runtime_errors and godot_script_diagnostics by the leak/teardown framing, though it never explicitly contrasts itself with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No statement of when to reach for this tool, no preconditions (e.g. must the engine be running, must the project have just been stopped), and no pointer to a sibling that covers a nearby case. The agent must infer from the name alone that this is a post-run or teardown diagnostic.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
godot_run_checkC
Run a command from the explicit project allowlist.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| timeout | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose one important behavioral trait: execution is restricted to an explicit project allowlist. However, it says nothing about what happens for non-allowlisted commands, whether execution is mutating or destructive, how output/exit status is returned, or how timeouts affect the run.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The definition is a single front-loaded sentence with no filler. It is concise to the point of under-specification, but the sentence itself earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a command-execution tool with no annotations, no output schema, and no parameter descriptions, the definition is missing the behavioral and parameter detail an agent needs to call it safely and correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only loosely implies that 'name' is an allowlisted command key, and it says nothing about the 'timeout' parameter, its units, or its 1–900 range.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action and constrained resource: running a command drawn from the project's explicit allowlist. It distinguishes itself from the sibling tools, which are all inspection/validation utilities, by being the only command executor. It stops short of clarifying what 'name' identifies or who owns the allowlist.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus the many inspection siblings, nor on preconditions such as how the allowlist is configured. The only implied rule is that the command must already be allowlisted, which is a constraint rather than usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
godot_runtime_errorsB
Return warning and error entries from the observer.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the source ('the observer') and entry types, but does not explain whether this is a read-only snapshot, whether entries are cleared, ordering, pagination, or any other runtime behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no wasted words. It is concise and structurally clear, though its brevity leaves out useful context rather than being maximally informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read tool with no output schema, the description states the source and content type but not the return shape, ordering, or relationship to sibling diagnostic tools. It is minimally viable but has clear gaps for an agent deciding how to interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there are no parameter semantics to document. Per the baseline for zero-parameter tools, a 4 is appropriate; the description does not need to compensate for schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb, 'Return,' and a specific resource, 'warning and error entries from the observer.' It is clear what the tool retrieves, but it does not distinguish this tool from close siblings such as godot_runtime_logs or godot_script_diagnostics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives. A reader can infer that it retrieves runtime warnings/errors, but there is no statement about when-not to use it or which sibling to choose for similar diagnostics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
godot_runtime_logsC
Read the bounded observer log ring buffer.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. 'Bounded' and 'ring buffer' hint that logs are limited and older entries are overwritten, but there is no information on return format, ordering, volume, or whether the read is purely observational.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no wasted words. For a zero-parameter read tool, this is appropriately sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, no annotations, and no parameter documentation, the description should explain what the logs contain and how they relate to sibling tools like godot_runtime_errors. It leaves an agent unable to judge the tool's output or selection criteria.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is no parameter semantics to document. The baseline score of 4 applies because the description does not need to compensate for an empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb (Read) and resource (log ring buffer), but 'bounded observer log ring buffer' is jargon-heavy and does not clarify what 'observer' logs contain or how this differs from siblings like godot_runtime_errors. An agent can infer it retrieves logs, but the scope remains vague.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus godot_runtime_errors or godot_runtime_snapshot. The implied usage is reading logs, but no conditions, alternatives, or exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
godot_runtime_propertyC
Read one runtime Node property from the read-only bridge.
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | ||
| property | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It does disclose the operation is read-only against a bridge, but says nothing about failure modes (node not found, property missing), whether the bridge must be attached/paused, or how values are serialized on return.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no wasted words. Brevity is appropriate, though one extra clause on node addressing would have been worth the space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Two required parameters, no output schema, and no annotations mean the description needs to explain input addressing and return shape. It explains neither, leaving the agent to guess how to target a node and what it gets back.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate and does not. It never clarifies whether 'node' is a scene path, a runtime pointer, or an instance id, nor whether 'property' is a simple name or a nested property path.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: reading a single runtime Node property via the read-only bridge. The scope word 'one' usefully signals this is a single-value fetch rather than a snapshot (godot_runtime_snapshot exists). It does not explicitly name a sibling it is not, so it stops short of 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No statement of when to use this versus godot_runtime_snapshot, godot_scene_inspect, or godot_runtime_logs, and no prerequisites (e.g. whether the game must be running or paused). The only implied guidance is 'read-only', which the agent must infer the boundaries of.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
godot_runtime_screenshotA
Capture a runtime viewport PNG as base64.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses the action and output format (base64 PNG), but does not say whether the game must be running, whether the capture has side effects, or what the response structure looks like beyond the encoding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It communicates the action, target, and output encoding efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no output schema, the description is nearly complete: it identifies the runtime viewport capture and states that the result is base64-encoded PNG. A bit more context about runtime requirements or expected response envelope would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, which is the baseline for a 4 under the rubric. There are no parameter semantics to clarify, and the description does not need to compensate for missing schema details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (Capture) and resource (runtime viewport PNG) plus the output encoding (base64). It is clear what the tool does, but it does not differentiate itself from the sibling godot_runtime_snapshot, which may be confused with this tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus alternatives such as godot_runtime_snapshot, nor are any prerequisites or exclusions mentioned. The intended usage is only implied by the name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
godot_runtime_snapshotC
Read one bounded page of runtime nodes and selected performance monitors.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| monitors | No | ||
| max_depth | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. 'Read' plus 'bounded page' weakly signals a read-only, paginated operation, but it says nothing about requiring a running/paused game, cost, whether the snapshot is a point-in-time copy, or failure behavior when no runtime session exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One front-loaded sentence with no filler — every clause carries meaning. It is terse to the point of under-specification, but that is penalized under other dimensions rather than for waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Four parameters at 0% schema coverage, no annotations, and no output schema means the description is the only guidance available, and one sentence about paging and monitors cannot convey the node-tree shape, depth behavior, or valid monitor identifiers an agent needs to call this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across four parameters. The description only gestures at pagination ('bounded page') and monitor selection ('selected performance monitors'); it never explains limit/offset semantics against max_depth, the allowed monitor names, the depth bound, or the default and maximum values baked into the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb ('Read') plus resources ('runtime nodes' and 'performance monitors') and a scoping trait ('one bounded page'). This distinguishes it from edit-time siblings like godot_scene_inspect and single-value reads like godot_runtime_property, but it never names those alternatives explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies a runtime-tooling context but gives no when-to-use conditions, no when-not-to-use, and no routing to alternatives (scene_inspect, runtime_property, runtime_logs). An agent must already know the tool landscape to pick this one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
godot_scene_inspectC
Inspect structured nodes, resources, scripts, and signals in a project scene.
| Name | Required | Description | Default |
|---|---|---|---|
| node | No | ||
| path | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full disclosure burden but delivers almost none — no statement that it is read-only, whether it walks the whole node tree or only the requested node, how large a listing may be, or whether the scene must be open/valid. "Inspect" weakly implies a read, but that is the only behavioral signal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler, and the object of inspection appears first. It is efficient, though its brevity reflects under-specification rather than tightness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Scene inspection spanning nodes, resources, scripts, and signals is a broad, potentially large-output operation, yet with no output schema, no annotations, and undocumented parameters the single sentence leaves the agent guessing about return shape and scope. Considerably more detail is required at this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description needed to explain the two parameters and did not. It never clarifies that "path" is the required scene path or what "node" does (scope to a subtree? a node path?), even though that distinction changes the call substantially.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ("Inspect") with a named resource ("project scene") and enumerates the inspected content types: nodes, resources, scripts, and signals. This is sufficient to distinguish it from godot_scene_patch (mutation) and godot_validate_scene (validation), though it never explicitly names the contrasting siblings such as godot_resource_inspect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to choose this over godot_resource_inspect or godot_project_info, and no prerequisites or exclusions are stated. A reader must infer that this summarizes a scene while its siblings inspect a resource or the whole project.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
godot_scene_patchB
Preview or apply one controlled scene property change; dry-run defaults to true.
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | ||
| path | Yes | ||
| value | Yes | ||
| dry_run | No | ||
| property | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so the description carries the full load. It does disclose the most important behavioral fact: dry_run defaults to true, so the safe path is the default and an agent must opt in to mutation. However it is silent on what persistence means, whether the write is atomic/reversible, what 'controlled' enforces, and whether a running editor conflicts.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One compact sentence, front-loaded with the action and mode, plus the dry-run default appended where it matters most. No filler, though the brevity is partly under-specification rather than tightness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A five-parameter mutation tool with no annotations, no output schema, and 0% schema coverage needs far more: parameter formats, dry-run response shape, and write-confirmation semantics are all missing. The single sentence is nowhere near sufficient for an agent to call this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and all five parameters are bare typed fields with no docs. The description explains only dry_run (its default), leaving path, node, property, and value — including expected formats such as a NodePath expression or property string — completely undefined.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
A specific verb pair (preview/apply) acting on a specific resource (a scene property change), with the scope qualifier 'one controlled' signalling a single-atom mutation. It doesn't explicitly contrast with the inspect/validate siblings, but the write-vs-read distinction is inferable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The mention of preview vs apply implies the two usage modes, but there is no explicit 'use this when...' guidance, no prerequisites (e.g. scene must exist / be closed), and no pointer to godot_scene_inspect or godot_validate_scene as the read-only alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
godot_script_diagnosticsC
Return bounded static diagnostics for a GDScript or C# file.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. 'Bounded' implies a result cap but the limit and truncation behavior are unexplained, and it doesn't confirm the operation is read-only or describe what diagnostics contain. A static analyzer is presumably safe, but the agent must infer that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler. It is efficient, though it is terse to the point of omitting useful detail rather than trimming waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a diagnostics tool with no output schema and no annotations, the description never indicates what the returned diagnostics look like (severity levels, line numbers, counts) or how 'bounded' manifests. An agent calling it cannot anticipate the response shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the sole `path` parameter is undocumented in the schema. The description partially compensates by implying path refers to a GDScript or C# source file, constraining the expected file type, but gives no format, relative-vs-absolute, or resolution guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Return bounded static diagnostics') and names the input domain (GDScript or C# file), which distinguishes it from runtime-oriented siblings like godot_runtime_errors and godot_runtime_logs. It stops short of explicitly naming those alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use or when-not-to-use guidance is given. The word 'static' hints that this differs from runtime error tools, but the description never states that alternative or the conditions that select it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
godot_stagehand_scenarioC
Run a configured Stagehand scenario and parse JUnit/visual diff outputs.
| Name | Required | Description | Default |
|---|---|---|---|
| timeout | No | ||
| scenario | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so the description carries the full burden. It hints at execution plus output parsing, but says nothing about side effects on the project, whether the run is isolated, how long it may take, or what the parsed results look like. Only a partial behavioral picture.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One front-loaded sentence with no filler, but the brevity here borders on under-specification for a tool that runs scenarios and diffs output.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A no-annotation, no-output-schema execution tool with fully undocumented parameters needs substantially more explanation than this single sentence provides. An agent lacks enough to call it confidently or interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description doesn't compensate: it never clarifies whether 'scenario' is a name, path, or identifier, nor does it mention the 'timeout' parameter (bounds 1-900s) at all. Both parameters remain semantically undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Run') and resource ('configured Stagehand scenario') plus the post-processing ('parse JUnit/visual diff outputs'). It is clearly distinguishable from the inspect/validate siblings, though 'Stagehand' is unexplained jargon that leaves the domain slightly opaque.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No indication of when to use this versus siblings like godot_run_check, what a 'configured' scenario means, or any prerequisites. The agent must infer the selection context entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
godot_validate_autoloadB
Validate project autoload paths.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It does not state whether validation is read-only, what conditions are checked, what happens on failure, or whether any project state is modified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no wasted words. It is concise, though its brevity contributes to gaps in usage and behavioral context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations and no output schema, the description should explain what validation checks and what kind of result the agent receives. It does neither, leaving an agent unable to know what a successful or failed validation means.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so parameter semantics are inherently simple. The baseline for a no-parameter tool is 4, and there is no schema complexity to explain beyond the empty input object.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Validate project autoload paths.' An agent can infer it checks autoload path configuration, but it does not explicitly distinguish this from the sibling godot_validate_scene.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool, when not to use it, or how it relates to alternatives such as godot_validate_scene. Usage is only implied by the word 'Validate.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
godot_validate_sceneC
Validate a project scene.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and delivers almost nothing: it does not say whether validation is read-only, what kinds of problems it detects (syntax, missing dependencies, broken references), or what happens on invalid input. Only the word 'validate' implies non-mutating behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short sentence with no filler, which is appropriately terse. However, the brevity reflects under-specification rather than disciplined editing, so it earns only a middling score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema and no annotations, so the description should explain what a validation result contains (errors, warnings, success indicator). Combined with the undocumented path parameter, an agent cannot confidently predict the call's behavior or response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single required parameter 'path' has 0% schema description coverage, so the description must explain it but does not. It never clarifies whether the path is a filesystem path or a res:// project path, or whether directories are accepted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
"Validate a project scene" gives a specific verb and resource, so the general intent is clear. But it never distinguishes itself from siblings like godot_scene_inspect or godot_run_check, leaving the agent unsure what 'validate' covers versus inspecting or running a check.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to call this versus godot_scene_inspect, godot_run_check, or godot_script_diagnostics, and no prerequisites or failure conditions are mentioned. The agent must infer usage purely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
15 tool updates
v0.2.0- First observed
godot_project_info - First observed
godot_resource_inspect - First observed
godot_resource_leaks - First observed
godot_run_check - First observed
godot_runtime_errors - First observed
godot_runtime_logs - First observed
godot_runtime_property - First observed
godot_runtime_screenshot - First observed
godot_runtime_snapshot - First observed
godot_scene_inspect - First observed
godot_scene_patch - First observed
godot_script_diagnostics - First observed
godot_stagehand_scenario - First observed
godot_validate_autoload - First observed
godot_validate_scene
TDQS
Scored across 15 tools
Most tools target clearly distinct scopes: project info, scene/resource inspection, runtime reads, diagnostics, validation, and controlled patching. There is some overlap among runtime diagnostics tools (logs, errors, leaks) and between scene inspection and scene validation, but the descriptions provide enough distinction for selection.
All names use snake_case and a consistent godot_ domain prefix, making them easy to scan. Most follow a scope_action or scope_noun pattern, though a few variants like godot_run_check and godot_stagehand_scenario are slightly less predictable.
Fifteen tools is well-scoped for a Godot project inspection, validation, and runtime debugging server. Each tool appears to cover a distinct operational area without obvious padding.
The surface covers project inspection, scene/resource inspection, validation, runtime observation, diagnostics, screenshots, allowlisted execution, and scenario testing. Minor gaps exist around broader scene/resource editing or creation, since scene_patch only previews/applies one controlled property change.
Maintenance
Related MCP Connectors
An MCP server that let you interact with Cycloid.io Internal Development Portal and Platform
Build your own tools from chat: design, test and host them on a shareable MCP server URL.
A MCP server built for developers enabling Git based project management with project and personal…
MCP server to assist with JxBrowser development.
Related MCP Servers
- AlicenseCqualityCmaintenanceEnables AI-driven game development by providing MCP tools to interact with the Godot editor, including scene editing, node manipulation, script attachment, and scene execution.288 npmMIT
- AlicenseAqualityDmaintenanceProvides AI assistants with tools to launch the Godot editor, run projects, manipulate scenes, manage scripts, and control node properties through a standardized MCP interface.21MIT
- AlicenseNot gradedqualityCmaintenanceProvides progressive-disclosure MCP access to Godot editor development, enabling tool discovery, task execution, inspection, and status tracking for projects across Godot 4.5 to 4.8-dev.MIT
- AlicenseCqualityCmaintenanceEnables MCP clients to inspect, validate, test, export, and query Godot projects, including live state from an open editor via a bridge addon.2017 npmMIT