Environment variables

All knobs are optional; the defaults serve a local single-user setup.

Server

Variable	Default	Meaning
GODOT_MCP_TRANSPORT	stdio	stdio or http
GODOT_MCP_HTTP_HOST	127.0.0.1	HTTP bind host
GODOT_MCP_HTTP_PORT	9090	HTTP bind port (/mcp is FastMCP's mount path)
GODOT_MCP_AUTH_TOKEN	unset	Bearer token; required for non-loopback HTTP binds (fail-fast, #226)
GODOT_MCP_HTTP_HOST_ORIGIN_PROTECTION	auto	HTTP Host/Origin (DNS-rebinding) guard (#636): auto validates the Host header + browser Origin for a loopback-bound server (foreign Host → 421, foreign Origin → 403); false opts out; true/strict validates every request
GODOT_MCP_BRIDGE_URL	ws://127.0.0.1:9080	bridge listen (server) / connect (addon) URL
GODOT_MCP_BRIDGE_TOKEN	unset	opt-in shared secret for the bridge handshake (#538) — when set, the addon must send the matching token as its first message or the peer is refused at the handshake; never logged
GODOT_MCP_PROJECT_DIR	unset	explicit project dir; else the connected editor's project is used
GODOT_MCP_DEFAULT_TOOLSETS	unset (= inspection)	seed the initial enabled toolsets: all or a comma-separated list (e.g. scene_edit,runtime); unknown names are logged and ignored
GODOT_MCP_GODOT_BIN	godot on PATH	the Godot binary the server shells out to for headless runs and parse/compile checks (distinct from the addon's editor; also settable as GODOT_BIN on CI)
GODOT_MCP_LOG_LEVEL	INFO	structured stderr logging level (JSON per line)
GODOT_MCP_APPROVAL_WEBHOOK	unset	human-in-the-loop approval endpoint for destructive tools (#153); unset → auto-approve
GODOT_MCP_APPROVAL_TIMEOUT	30.0	per-approval-request timeout, seconds
GODOT_MCP_APPROVAL_FAIL_OPEN	false	on an unreachable/slow webhook: false denies (fail closed, #638), true approves
GODOT_MCP_CHECK_UPDATES	unset (= off)	opt-in update check (#629): when set (1/true/yes) the server may query the release feed so godot_check_for_updates can report a newer release; unset = no network

Addon (read in the editor's environment)

Variable	Default	Meaning
GODOT_MCP_BRIDGE_URL	ws://127.0.0.1:9080	where the addon dials the server (same var as the server)
GODOT_MCP_BRIDGE_TOKEN	unset	the same opt-in secret as the server — the addon authenticates with it as its first message after connecting; never logged
GODOT_MCP_AUTO_REFRESH	unset (= off)	opt-in timer-based filesystem auto-refresh (#561): 1/true/yes enables a periodic EditorFileSystem.scan() so external edits (agents, git, other tools) show up without editor focus; the dock checkbox is the runtime override
GODOT_MCP_AUTO_REFRESH_INTERVAL	10	seconds between auto-refresh scans (floor 2s; only read when GODOT_MCP_AUTO_REFRESH is on)
GODOT_BIN	godot on PATH	where a CI workflow points the server's binary lookup (e2e.yml Actions var) — the server itself reads GODOT_MCP_GODOT_BIN, then godot/Godot on PATH, then the macOS app bundle

Security model

Mode	Bind	Auth	Why
stdio (default)	N/A (local subprocess)	none	only the spawning client can talk to it
http on loopback	127.0.0.1	none	only local processes reach it
http non-loopback	0.0.0.0 / external IP	GODOT_MCP_AUTH_TOKEN required	the server refuses to start otherwise (#226) — without a token, anyone on the network could write scripts, run the game, or export builds through your editor

# Generate + set a token
TOKEN=$(openssl rand -hex 32)
GODOT_MCP_TRANSPORT=http GODOT_MCP_HTTP_HOST=0.0.0.0 GODOT_MCP_AUTH_TOKEN=$TOKEN \
  uv run godot-editor-mcp

Clients pass the same token (HTTP Authorization: Bearer … header).

Bridge handshake auth (#538)

The editor↔server WebSocket bridge is localhost-only; the bridge token adds a shared secret for shared/self-hosted runners and remote-editor setups. It is opt-in on each side — unset means no auth (zero-config local dev, unchanged path). Both sides read GODOT_MCP_BRIDGE_TOKEN.

Server token	Addon token	Behavior
unset	unset	today's path — no auth exchange (byte-identical)
set	set, matching	peer authenticated, everything serves
set	set, mismatched	structured refusal at the handshake; the addon drops into its reconnect/backoff loop and the dock log shows the refusal reason each attempt until the tokens agree
set	unset	refused at the handshake (the addon never authenticates) — same visible reconnect loop
unset	set	the server consumes the auth envelope as a control message and serves anyway (forward-compatible: a newer addon against an older server)

A refusal happens at the handshake — never as per-command errors, never as a silent drop. Tokens are compared in constant time and are never logged on either side.

# Shared/self-hosted runner: pin the same token on both sides
TOKEN=$(openssl rand -hex 32)
GODOT_MCP_BRIDGE_TOKEN=$TOKEN uv run godot-editor-mcp          # server
GODOT_MCP_BRIDGE_TOKEN=$TOKEN godot --editor --path ./game     # the editor's env

Listener hardening (#636)

Browsers do not apply the same-origin policy to WebSockets, and DNS rebinding can make a page the user visits resolve to 127.0.0.1. Both listeners are hardened by default:

• Bridge WebSocket: the listener accepts only Origin-less handshakes (origins=[None]) — the Godot addon's WebSocketPeer sends no Origin, so a browser page is rejected at the handshake (403) before it can reach the bridge. A bad-or-missing-token peer is also refused before it can displace the authenticated editor (#635).
• HTTP transport: FastMCP's HostOriginGuardMiddleware is enabled by default (GODOT_MCP_HTTP_HOST_ORIGIN_PROTECTION=auto), so a non-loopback Host header is refused (421) and a foreign browser Origin is refused (403) before any code-executing tool (write_script, run_and_capture, export_project) is reachable. Opt out with GODOT_MCP_HTTP_HOST_ORIGIN_PROTECTION=false.

Neither guard replaces the auth token — a non-loopback HTTP bind still requires GODOT_MCP_AUTH_TOKEN.

Logging

Logs are one JSON object per line on stderr (stdout is the stdio protocol channel). Every log line carries the command id where applicable; errors include exception info. No secrets or full file contents are logged.