@satelliteoflove/godot-mcp 3.8.0 → 3.10.0

package/README.md

@@ -14,6 +14,8 @@ This MCP gives Claude direct access to your Godot editor. It can see your scene
 
 Add godot-mcp to your MCP client. See the [Installation Guide](INSTALL.md) for config examples (Claude Desktop, Claude Code, VSCode/Copilot, and more).
 
+While you're at it, add [minimal-godot-mcp](https://github.com/ryanmazzolini/minimal-godot-mcp) too — it's a complementary server that covers static GDScript diagnostics and the running game's console output. See [Works Well With](#works-well-with).
+
 ### 2. Install the Godot addon
 
 ```bash
@@ -28,7 +30,7 @@ Open your Godot project, restart your AI assistant, and start building.
 
 ## What Claude Can Do
 
-- **See** your editor, scenes, running game, errors, and performance
+- **See** your editor, scenes, running game, editor errors, and performance
 - **Inspect** nodes, resources, animations, tilemaps, 3D spatial data
 - **Modify** scenes, nodes, scripts, animations, tilemaps directly
 - **Test** by running the game and injecting input
@@ -36,9 +38,11 @@ Open your Godot project, restart your AI assistant, and start building.
 
 ## Works Well With
 
-[minimal-godot-mcp](https://github.com/ryanmazzolini/minimal-godot-mcp) by [@ryanmazzolini](https://github.com/ryanmazzolini) is another MCP server for Godot. It focuses on language server diagnostics and console output via DAP, with no addon required. This project focuses on runtime control, scene manipulation, and everything that needs a direct line into the editor.
+[minimal-godot-mcp](https://github.com/ryanmazzolini/minimal-godot-mcp) by [@ryanmazzolini](https://github.com/ryanmazzolini) is another MCP server for Godot, and it's worth running alongside this one. This server drives the editor through an addon — scene and node manipulation, running the game, input injection, runtime state, screenshots, and editor-side errors (`@tool`, import, and addon failures). minimal-godot-mcp needs no addon and provides exactly the functionality this server does not implement: LSP diagnostics for fast static `.gd` checking, and the running game's console output and stderr over DAP.
+
+Neither duplicates the other, and they don't conflict. Install both and you get static analysis and the live game console alongside full editor and runtime control.
 
-They don't overlap much, and they don't conflict. Run them side by side for the best coverage.
+**One godot-mcp client at a time, though.** A Godot editor bridge serves a single godot-mcp connection. If a second godot-mcp client connects - for example, a subagent that inherited the same MCP config - it is rejected while the first is active rather than displacing it, so the original session keeps working. The second client retries and connects automatically once the first disconnects. A client that crashes without closing its socket is taken over after a short idle timeout, so a dead session never permanently blocks new connections.
 
 ## Documentation
 

package/addon/commands/debug_commands.gd

@@ -116,24 +116,16 @@ func _on_debug_output_received(output: PackedStringArray) -> void:
 
 func get_log_messages(params: Dictionary) -> Dictionary:
 	var clear: bool = params.get("clear", false)
-	var limit: int = params.get("limit", 50)
+	var limit: int = int(params.get("limit", 50))
+	var severity: String = params.get("severity", "all")
+	var since: int = int(params.get("since", 0))
 
-	var all_messages := MCPLogger.get_errors()
-	var total_count := all_messages.size()
-
-	var limited: Array[Dictionary] = []
-	var start_index := maxi(0, total_count - limit)
-	for i in range(start_index, total_count):
-		limited.append(all_messages[i])
+	var result := MCPLogger.query(since, severity, limit)
 
 	if clear:
 		MCPLogger.clear_errors()
 
-	return _success({
-		"total_count": total_count,
-		"returned_count": limited.size(),
-		"messages": limited,
-	})
+	return _success(result)
 
 
 func get_errors(params: Dictionary) -> Dictionary:

package/addon/commands/game_time_commands.gd

@@ -2,11 +2,11 @@
 extends MCPBaseCommand
 class_name MCPGameTimeCommands
 
-# Game-time control relay: freeze / step / thaw / status execute in the game
-# bridge (see mcp_game_bridge.gd); this side only forwards over the debugger
-# channel and waits. Timeout cascade: the step request is capped at 20s of
-# game time and the bridge's wall budget returns by 25s, so the 28s relay
-# timeout below fires only if the bridge is gone — and stays under the
+# Game-time control relay: freeze / step / step_until / thaw / status execute in
+# the game bridge (see mcp_game_bridge.gd); this side only forwards over the
+# debugger channel and waits. Timeout cascade: a step/step_until request is
+# capped at 20s of game time and the bridge's wall budget returns by 25s, so the
+# 28s relay timeout below fires only if the bridge is gone — and stays under the
 # server's 30s command timeout so errors surface typed instead of generic.
 const BASE_TIMEOUT := 10.0
 const STEP_TIMEOUT := 28.0
@@ -18,6 +18,7 @@ func get_commands() -> Dictionary:
 	return {
 		"game_time_freeze": game_time_freeze,
 		"game_time_step": game_time_step,
+		"game_time_step_until": game_time_step_until,
 		"game_time_thaw": game_time_thaw,
 		"game_time_status": game_time_status,
 	}
@@ -31,6 +32,10 @@ func game_time_step(params: Dictionary) -> Dictionary:
 	return await _relay("game_time_step", [params], STEP_TIMEOUT)
 
 
+func game_time_step_until(params: Dictionary) -> Dictionary:
+	return await _relay("game_time_step_until", [params], STEP_TIMEOUT)
+
+
 func game_time_thaw(params: Dictionary) -> Dictionary:
 	return await _relay("game_time_thaw", [params], BASE_TIMEOUT)
 

package/addon/commands/system_commands.gd

@@ -3,10 +3,14 @@ extends MCPBaseCommand
 class_name MCPSystemCommands
 
 
+const RESTART_ACK_GRACE_SEC := 0.3
+
+
 func get_commands() -> Dictionary:
 	return {
 		"mcp_handshake": mcp_handshake,
 		"heartbeat": heartbeat,
+		"restart_editor": restart_editor,
 	}
 
 
@@ -29,6 +33,25 @@ func heartbeat(_params: Dictionary) -> Dictionary:
 	return _success({"status": "ok"})
 
 
+func restart_editor(params: Dictionary) -> Dictionary:
+	var save: bool = params.get("save", true)
+
+	# Restarting tears down this websocket along with the editor, so defer the
+	# actual restart by a short grace period. That lets this acknowledgement
+	# flush to the client first; the MCP server then auto-reconnects once the
+	# editor is back. (EditorInterface.restart_editor itself defers the quit to
+	# end-of-frame, which alone is too early for the response to make it out.)
+	var tree := Engine.get_main_loop() as SceneTree
+	if tree:
+		tree.create_timer(RESTART_ACK_GRACE_SEC).timeout.connect(
+			func() -> void: EditorInterface.restart_editor(save)
+		)
+	else:
+		EditorInterface.restart_editor(save)
+
+	return _success({"restarting": true, "save": save})
+
+
 func _get_addon_version() -> String:
 	var config := ConfigFile.new()
 	var err := config.load("res://addons/godot_mcp/plugin.cfg")

package/addon/core/mcp_logger.gd

@@ -6,6 +6,11 @@ static var _errors: Array[Dictionary] = []
 static var _max_lines := 1000
 static var _max_errors := 100
 static var _mutex := Mutex.new()
+# Monotonic sequence stamped on every retained error, never reset (not even by
+# clear_errors). It is the cursor for incremental reads: a caller passes the
+# `cursor` from a previous get_log_messages back as `since` to get only what is
+# new. Independent of array index, so trimming the oldest entries is harmless.
+static var _seq := 0
 
 
 static func _static_init() -> void:
@@ -50,6 +55,8 @@ func _log_error(function: String, file: String, line: int, code: String,
 		"frames": frames,
 	}
 	if not _is_duplicate(error_entry):
+		_seq += 1
+		error_entry["seq"] = _seq
 		_errors.append(error_entry)
 		if _errors.size() > _max_errors:
 			_errors.remove_at(0)
@@ -74,6 +81,58 @@ static func get_errors() -> Array[Dictionary]:
 	return _errors
 
 
+static func get_seq() -> int:
+	return _seq
+
+
+# Filtered, incremental view of the retained errors. Pure (no side effects) so it
+# can be unit-tested headless.
+#   since    : return only entries with seq > since (0 = from the beginning)
+#   severity : "all" (default), "error" (drops warnings), or "warning" (only warnings)
+#   limit    : keep at most this many of the most recent matches (<= 0 means all)
+# `cursor` is always the highest seq issued so far; pass it back as `since` next
+# time to read only what is new. `total_count` is the whole buffer (unfiltered),
+# `match_count` is what passed the filters, `returned_count` is after the limit.
+static func query(since: int, severity: String, limit: int) -> Dictionary:
+	_mutex.lock()
+	var cursor := _seq
+	var total_count := _errors.size()
+	var matched: Array[Dictionary] = []
+	for entry in _errors:
+		if int(entry.get("seq", 0)) <= since:
+			continue
+		if not _severity_matches(severity, int(entry.get("error_type", 0))):
+			continue
+		matched.append(entry)
+	_mutex.unlock()
+
+	var match_count := matched.size()
+	var start_index := 0
+	if limit > 0 and match_count > limit:
+		start_index = match_count - limit
+	var messages: Array[Dictionary] = matched.slice(start_index)
+
+	return {
+		"total_count": total_count,
+		"match_count": match_count,
+		"returned_count": messages.size(),
+		"cursor": cursor,
+		"messages": messages,
+	}
+
+
+# Logger.ErrorType (inherited): ERROR_TYPE_ERROR=0, ERROR_TYPE_WARNING=1,
+# ERROR_TYPE_SCRIPT=2, ERROR_TYPE_SHADER=3. Only WARNING is not an actual problem.
+static func _severity_matches(severity: String, error_type: int) -> bool:
+	match severity:
+		"error":
+			return error_type != Logger.ERROR_TYPE_WARNING
+		"warning":
+			return error_type == Logger.ERROR_TYPE_WARNING
+		_:
+			return true
+
+
 static func get_last_stack_trace() -> Array[Dictionary]:
 	if _errors.is_empty():
 		return []

package/addon/game_bridge/mcp_game_bridge.gd

@@ -170,6 +170,9 @@ func _on_debugger_message(message: String, data: Array) -> bool:
 		"game_time_step":
 			_handle_game_time_step(data)
 			return true
+		"game_time_step_until":
+			_handle_game_time_step_until(data)
+			return true
 		"game_time_thaw":
 			_handle_game_time_thaw(data)
 			return true
@@ -1117,6 +1120,18 @@ var _step_events_fired := 0
 var _step_transitions: Array = []
 var _step_last_tree_paused := false
 
+# step_until adds a predicate evaluated each frame. _step_predicate is null for a
+# fixed-budget step, set for step_until; _step_response_type routes _finish_step's
+# reply to the matching command (the relay correlates by message type). _step_report
+# is the optional readings the agent wants back at stop time (in one round-trip,
+# instead of a separate observation call) — each is [{src: String, expr: Expression}].
+var _step_predicate: Expression = null
+var _step_predicate_inputs: Array = []
+var _step_predicate_met := false
+var _step_predicate_error := ""
+var _step_report: Array = []
+var _step_response_type := "game_time_step"
+
 
 func _send_game_time_response(msg_type: String, result: Dictionary) -> void:
 	EngineDebugger.send_message("godot_mcp:game_response", [msg_type, result])
@@ -1235,15 +1250,53 @@ func _handle_game_time_step(data: Array) -> void:
 	# from window start). Inputs must ride inside the step: an event injected
 	# while frozen lands on a frame gameplay never processes, so its
 	# is_action_just_pressed edge would be silently missed.
-	var inputs: Array = params.get("inputs", [])
+	var compiled := _compile_step_events(params.get("inputs", []))
+	if compiled.has("error"):
+		_send_game_time_response("game_time_step", {"error": compiled["error"]})
+		return
+
+	# Step from a running game is allowed — it freezes first, so "advance
+	# 500ms then wait for me" is a single atomic call.
+	_engage_freeze()
+
+	_step_target_ms = float(duration_ms)
+	_step_target_frames = frames
+	_step_elapsed_ms = 0.0
+	_step_gameplay_ms = 0.0
+	_step_frames = 0
+	_step_physics_ticks = 0
+	_step_events = compiled["events"]
+	_step_events_fired = 0
+	_step_transitions = []
+	_step_needs_settle = false
+	_step_finish_pending = false
+	_step_wall_exceeded = false
+	_step_wall_start = Time.get_ticks_msec()
+	_step_predicate = null
+	_step_response_type = "game_time_step"
+	_step_active = true
+
+	# Open the window: restore the game layer's own pause wish for the
+	# duration. If the game's menu is holding it paused, the window still
+	# elapses (and reports gameplay_ms ~0) — never deadlock waiting for
+	# gameplay time that cannot come.
+	var tree := get_tree()
+	tree.paused = _game_paused
+	_step_last_tree_paused = tree.paused
+	set_physics_process(true)
+	_update_processing()
+
+
+func _compile_step_events(inputs: Array) -> Dictionary:
+	# Builds the press/release timeline shared by step and step_until. start_ms
+	# is game time from window start; returns {"error": ...} on an unknown action.
 	var events: Array = []
 	for input in inputs:
 		var action_name: String = input.get("action_name", "")
 		if action_name.is_empty():
 			continue
 		if not InputMap.has_action(action_name):
-			_send_game_time_response("game_time_step", {"error": "Unknown action: %s" % action_name})
-			return
+			return {"error": "Unknown action: %s" % action_name}
 		var start_ms: int = int(input.get("start_ms", 0))
 		var dur: int = int(input.get("duration_ms", 0))
 		events.append({"time": start_ms, "action": action_name, "is_press": true})
@@ -1251,30 +1304,163 @@ func _handle_game_time_step(data: Array) -> void:
 	events.sort_custom(func(a: Dictionary, b: Dictionary) -> bool:
 		return a.time < b.time
 	)
+	return {"events": events}
+
+
+func _build_predicate_context() -> Dictionary:
+	# Exposes the running game to a step_until predicate: every autoload by its
+	# own name (so `G.wave > 1` just works), plus `tree` (SceneTree) and `root`
+	# (root Window) for tree queries like
+	# `tree.get_nodes_in_group("enemies").size() >= 1`. Chained calls must run on
+	# these input objects, not the Expression base instance, so they are inputs.
+	var names: Array = []
+	var inputs: Array = []
+	var tree := get_tree()
+	for prop in ProjectSettings.get_property_list():
+		var key: String = prop.get("name", "")
+		if not key.begins_with("autoload/"):
+			continue
+		var autoload_name := key.substr("autoload/".length())
+		var node := tree.root.get_node_or_null(NodePath(autoload_name))
+		if node == null or node == self:
+			continue  # skip the bridge's own autoload and any unresolved entry
+		names.append(autoload_name)
+		inputs.append(node)
+	if not names.has("tree"):
+		names.append("tree")
+		inputs.append(tree)
+	if not names.has("root"):
+		names.append("root")
+		inputs.append(tree.root)
+	return {"names": PackedStringArray(names), "inputs": inputs}
+
+
+func _sanitize_value(v: Variant) -> Variant:
+	# Report values ride back over the debugger channel. Pass primitives through;
+	# never try to serialize Objects/containers — a short string stand-in is
+	# enough for the agent to see what an expression evaluated to.
+	match typeof(v):
+		TYPE_NIL, TYPE_BOOL, TYPE_INT, TYPE_FLOAT, TYPE_STRING, TYPE_STRING_NAME:
+			return v
+		_:
+			return str(v).substr(0, 200)
+
+
+func _compile_report(report: Array, names: PackedStringArray, inputs: Array) -> Dictionary:
+	# Compile + validate each report expression in the predicate context. Returns
+	# {"error": ...} if any fails up front, else {"report": [{src, expr}, ...]}.
+	var compiled: Array = []
+	for item in report:
+		var s := str(item).strip_edges()
+		if s.is_empty():
+			continue
+		var e := Expression.new()
+		if e.parse(s, names) != OK:
+			return {"error": "report expression parse error (%s): %s" % [s, e.get_error_text()]}
+		e.execute(inputs, self)
+		if e.has_execute_failed():
+			return {"error": "report expression failed to evaluate (%s): %s" % [s, e.get_error_text()]}
+		compiled.append({"src": s, "expr": e})
+	return {"report": compiled}
+
+
+func _evaluate_report(report_exprs: Array, inputs: Array) -> Dictionary:
+	# Evaluate the compiled report expressions at stop time into {src: value}.
+	var out: Dictionary = {}
+	for item in report_exprs:
+		var e: Expression = item["expr"]
+		var v: Variant = e.execute(inputs, self)
+		if e.has_execute_failed():
+			out[item["src"]] = "<error: %s>" % e.get_error_text()
+		else:
+			out[item["src"]] = _sanitize_value(v)
+	return out
+
+
+func _handle_game_time_step_until(data: Array) -> void:
+	var params: Dictionary = data[0] if data.size() > 0 and data[0] is Dictionary else {}
+	if _step_active:
+		_send_game_time_response("game_time_step_until", {"error": "Step already in progress"})
+		return
+
+	var src: String = str(params.get("until", "")).strip_edges()
+	if src.is_empty():
+		_send_game_time_response("game_time_step_until", {"error": "step_until requires a non-empty `until` expression"})
+		return
+
+	var max_ms: int = int(params.get("max_ms", STEP_MAX_MS))
+	if max_ms <= 0:
+		max_ms = STEP_MAX_MS
+	max_ms = mini(max_ms, STEP_MAX_MS)
+
+	# Compile and validate the predicate against the live tree before committing
+	# to a step. Expression.parse() is lenient (a malformed string can parse
+	# clean), so a dry-run execute is what actually catches unknown identifiers
+	# and bad member access.
+	var ctx := _build_predicate_context()
+	var ctx_names: PackedStringArray = ctx["names"]
+	var ctx_inputs: Array = ctx["inputs"]
+	var expr := Expression.new()
+	if expr.parse(src, ctx_names) != OK:
+		_send_game_time_response("game_time_step_until", {"error": "predicate parse error: %s" % expr.get_error_text()})
+		return
+	var first_value: Variant = expr.execute(ctx_inputs, self)
+	if expr.has_execute_failed():
+		_send_game_time_response("game_time_step_until", {"error": "predicate failed to evaluate: %s" % expr.get_error_text()})
+		return
+
+	# Optional readings to return at stop time, validated up front in the same context.
+	var report_result := _compile_report(params.get("report", []), ctx_names, ctx_inputs)
+	if report_result.has("error"):
+		_send_game_time_response("game_time_step_until", {"error": report_result["error"]})
+		return
+	var report_compiled: Array = report_result["report"]
+
+	var compiled := _compile_step_events(params.get("inputs", []))
+	if compiled.has("error"):
+		_send_game_time_response("game_time_step_until", {"error": compiled["error"]})
+		return
 
-	# Step from a running game is allowed — it freezes first, so "advance
-	# 500ms then wait for me" is a single atomic call.
 	_engage_freeze()
 
-	_step_target_ms = float(duration_ms)
-	_step_target_frames = frames
+	# Predicate already holds: advance nothing, stay frozen, report it.
+	if bool(first_value):
+		var sc_result: Dictionary = {
+			"completed": true,
+			"frozen": true,
+			"elapsed_ms": 0,
+			"gameplay_ms": 0,
+			"frames": 0,
+			"physics_ticks": 0,
+			"game_paused": _game_paused,
+			"predicate_met": true,
+		}
+		if not report_compiled.is_empty():
+			sc_result["report"] = _evaluate_report(report_compiled, ctx_inputs)
+		_send_game_time_response("game_time_step_until", sc_result)
+		return
+
+	_step_target_ms = float(max_ms)
+	_step_target_frames = 0
 	_step_elapsed_ms = 0.0
 	_step_gameplay_ms = 0.0
 	_step_frames = 0
 	_step_physics_ticks = 0
-	_step_events = events
+	_step_events = compiled["events"]
 	_step_events_fired = 0
 	_step_transitions = []
 	_step_needs_settle = false
 	_step_finish_pending = false
 	_step_wall_exceeded = false
 	_step_wall_start = Time.get_ticks_msec()
+	_step_predicate = expr
+	_step_predicate_inputs = ctx_inputs
+	_step_predicate_met = false
+	_step_predicate_error = ""
+	_step_report = report_compiled
+	_step_response_type = "game_time_step_until"
 	_step_active = true
 
-	# Open the window: restore the game layer's own pause wish for the
-	# duration. If the game's menu is holding it paused, the window still
-	# elapses (and reports gameplay_ms ~0) — never deadlock waiting for
-	# gameplay time that cannot come.
 	var tree := get_tree()
 	tree.paused = _game_paused
 	_step_last_tree_paused = tree.paused
@@ -1325,6 +1511,19 @@ func _step_process(delta: float) -> void:
 		done = _step_frames >= _step_target_frames
 	else:
 		done = _step_elapsed_ms >= _step_target_ms
+
+	# step_until: re-evaluate the predicate each frame against the advancing
+	# game. A truthy result stops the window early; a runtime failure (e.g. a
+	# watched node was freed mid-window) ends it honestly with the error attached.
+	if _step_predicate != null:
+		var v: Variant = _step_predicate.execute(_step_predicate_inputs, self)
+		if _step_predicate.has_execute_failed():
+			_step_predicate_error = _step_predicate.get_error_text()
+			done = true
+		elif bool(v):
+			_step_predicate_met = true
+			done = true
+
 	if Time.get_ticks_msec() - _step_wall_start > STEP_WALL_BUDGET_MS:
 		# Slow-mo, Engine.time_scale = 0, or a pause-held window can starve
 		# the game-time clock; the wall budget guarantees the call returns
@@ -1376,4 +1575,19 @@ func _finish_step() -> void:
 		result["pause_transitions"] = _step_transitions
 	if _step_wall_exceeded:
 		result["wall_budget_exceeded"] = true
-	_send_game_time_response("game_time_step", result)
+	if _step_predicate != null:
+		# step_until: predicate_met is the headline. report carries the readings the
+		# agent asked for (the "what advanced" hint, so it need not re-observe). A
+		# non-met return means the cap or wall budget ran out first.
+		result["predicate_met"] = _step_predicate_met
+		if not _step_report.is_empty():
+			result["report"] = _evaluate_report(_step_report, _step_predicate_inputs)
+		if not _step_predicate_error.is_empty():
+			result["predicate_error"] = _step_predicate_error
+
+	# Route the reply to the originating command — the relay correlates by type.
+	var response_type := _step_response_type
+	_step_predicate = null
+	_step_predicate_inputs = []
+	_step_report = []
+	_send_game_time_response(response_type, result)

package/addon/plugin.cfg

@@ -3,6 +3,6 @@
 name="Godot MCP"
 description="Model Context Protocol server for AI assistant integration"
 author="godot-mcp"
-version="3.8.0"
+version="3.10.0"
 script="plugin.gd"
 godot_version_min="4.5"

package/addon/websocket_server.gd

@@ -8,10 +8,14 @@ signal client_disconnected()
 
 const DEFAULT_PORT := 6550
 const STALE_CONNECTION_TIMEOUT_MSEC := 45000
+# Upper bound on how long a rejected newcomer is kept around while we hand it a
+# clean 4001 close. Caps the whole reject lifecycle (handshake + close flush) so
+# a peer that never upgrades or never finishes closing can't leak.
+const REJECT_TIMEOUT_MSEC := 5000
 const CLOSE_CODE_STALE := 4002
 const CLOSE_REASON_STALE := "Connection timed out (no activity)"
-const CLOSE_CODE_REPLACED := 4003
-const CLOSE_REASON_REPLACED := "Replaced by new client"
+const CLOSE_CODE_ALREADY_CONNECTED := 4001
+const CLOSE_REASON_ALREADY_CONNECTED := "Another client is already connected"
 
 var _server: TCPServer
 var _peer: StreamPeerTCP
@@ -21,6 +25,10 @@ var _connected_host: String = ""
 var _connected_port: int = 0
 var _last_activity_msec: int = 0
 var _stale_reason: String = ""
+# Newcomers that arrived while a live client already held the bridge. Each entry
+# is { "ws": WebSocketPeer, "tcp": StreamPeerTCP, "since_msec": int, "close_sent": bool }.
+# They are handshaked just far enough to receive a clean 4001 close, then dropped.
+var _rejecting_peers: Array = []
 
 
 func _process(_delta: float) -> void:
@@ -34,6 +42,9 @@ func _process(_delta: float) -> void:
 		_ws_peer.poll()
 		_process_websocket()
 
+	if not _rejecting_peers.is_empty():
+		_process_rejecting_peers()
+
 
 func start_server(port: int = DEFAULT_PORT, bind_address: String = "127.0.0.1") -> Error:
 	_server = TCPServer.new()
@@ -55,6 +66,15 @@ func stop_server() -> void:
 		_peer.disconnect_from_host()
 		_peer = null
 
+	for entry in _rejecting_peers:
+		var rej_ws: WebSocketPeer = entry.get("ws")
+		if rej_ws:
+			rej_ws.close()
+		var rej_tcp: StreamPeerTCP = entry.get("tcp")
+		if rej_tcp:
+			rej_tcp.disconnect_from_host()
+	_rejecting_peers.clear()
+
 	if _server:
 		_server.stop()
 		_server = null
@@ -89,11 +109,19 @@ func _accept_connection() -> void:
 
 	if _ws_peer != null:
 		if _is_stale_connection():
+			# The incumbent looks dead (TCP dropped, or no activity past the
+			# timeout). Hand the bridge to the newcomer so a crashed client can
+			# never permanently block reconnection.
 			MCPLog.warn("Replacing stale connection with new client (%s)" % _stale_reason)
 			_force_close_connection()
 		else:
-			MCPLog.warn("Replacing active connection with new client (previous server likely exited without closing)")
-			_force_close_connection(CLOSE_CODE_REPLACED, CLOSE_REASON_REPLACED)
+			# A live client already holds the bridge. Protect the incumbent and
+			# reject the newcomer with a clean close code instead of displacing
+			# it. This keeps a transient second client (e.g. a subagent that
+			# inherited the same MCP config) from bricking the active session.
+			MCPLog.warn("Rejecting new connection from %s:%d: another client is already connected" % [incoming.get_connected_host(), incoming.get_connected_port()])
+			_begin_reject(incoming)
+			return
 
 	_peer = incoming
 	_ws_peer = WebSocketPeer.new()
@@ -112,6 +140,64 @@ func _accept_connection() -> void:
 	MCPLog.info("TCP connection received from %s:%d, awaiting WebSocket handshake..." % [_connected_host, _connected_port])
 
 
+func _begin_reject(incoming: StreamPeerTCP) -> void:
+	# Complete just enough of the WebSocket handshake on a throwaway peer to send
+	# a proper coded close frame (4001), so the rejected client gets a clear
+	# diagnostic rather than an opaque TCP reset. The incumbent's peer is never
+	# touched. Driven to completion in _process_rejecting_peers().
+	var ws := WebSocketPeer.new()
+	var err := ws.accept_stream(incoming)
+	if err != OK:
+		# Can't speak WebSocket to this peer; just drop the raw TCP connection.
+		incoming.disconnect_from_host()
+		return
+	_rejecting_peers.append({
+		"ws": ws,
+		"tcp": incoming,
+		"since_msec": Time.get_ticks_msec(),
+		"close_sent": false,
+	})
+
+
+func _process_rejecting_peers() -> void:
+	var keep: Array = []
+	var now := Time.get_ticks_msec()
+	for entry in _rejecting_peers:
+		var ws: WebSocketPeer = entry["ws"]
+		ws.poll()
+		var state := ws.get_ready_state()
+
+		# Hard lifecycle cap: a reject peer should resolve in milliseconds.
+		# Anything still around past the timeout (never upgraded, or stuck
+		# mid-close because the client vanished) gets dropped so it can't leak.
+		if now - int(entry["since_msec"]) > REJECT_TIMEOUT_MSEC:
+			_drop_rejecting_peer(entry)
+			continue
+
+		match state:
+			WebSocketPeer.STATE_OPEN:
+				if not entry["close_sent"]:
+					ws.close(CLOSE_CODE_ALREADY_CONNECTED, CLOSE_REASON_ALREADY_CONNECTED)
+					entry["close_sent"] = true
+				# Keep polling so the close frame is actually flushed.
+				keep.append(entry)
+			WebSocketPeer.STATE_CLOSED:
+				_drop_rejecting_peer(entry)
+			_:
+				# STATE_CONNECTING (awaiting handshake) or STATE_CLOSING
+				# (flushing the close frame) - keep polling until the cap.
+				keep.append(entry)
+	_rejecting_peers = keep
+
+
+func _drop_rejecting_peer(entry: Dictionary) -> void:
+	var tcp: StreamPeerTCP = entry.get("tcp")
+	if tcp:
+		tcp.disconnect_from_host()
+	entry["ws"] = null
+	entry["tcp"] = null
+
+
 func _process_websocket() -> void:
 	if not _ws_peer:
 		return

package/dist/__tests__/connection/websocket.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=websocket.test.d.ts.map

package/dist/__tests__/connection/websocket.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/connection/websocket.test.ts"],"names":[],"mappings":""}