Common failure modes and their fixes, roughly by how often they hit. Your first stop is always get_bridge_status, a real round-trip through the editor that reports the bridge version and handler count.
The native MCP server is hosted by the editor process. If s&box isn't running, there is no server. Start s&box and open your project, then check Editor → Preferences → MCP Server: it's on by default at port 7269; enable it if it's been switched off (and if you changed the port, update the URL you registered with claude mcp add). Still dead with the editor running? See the next item.
A stale HTTP.sys registrationfrom a dying editor instance still holds the port: a previous editor process crashed or was still shutting down when the new one started, so the new instance couldn't bind, logged the line once, and carried on without the server. Make sure the stale s&box process has actually exited (check Task Manager), then restart the editor. The bind succeeds once the stale holder is gone.
search_tools finds the native built-ins but no bridge_*toolsets? The bridge's tools are discovered from the claudebridge addon's compiled editor assembly. If the library isn't installed in the openproject, or its C# isn't compiling, the engine has nothing to discover. Confirm it's installed (Editor → Library Manager → sboxskinsgg.claudebridge; it must live in your project's Libraries/), then check for compile failures with compile_statusor the lifeline's get_compile_errors. Toolsets hot-register within seconds of a clean compile, no restart needed.
Just read the error: get_compile_errors and read_log live on the lifeline server, so they work even when the editor is in a broken state. Fix the file the error names, trigger_hotload, and re-check. If game code fails to compile, the editor-side bridge fails too (Broken Reference: package.local.X), fix the game code first.
The native server lives inside the editor process and dies with it. Nothing served over port 7269 can tell you why the editor went down. That's what the lifeline is for: it runs outside the editor, and its read_log / get_compile_errors keep answering when nothing else does. Diagnose, fix, relaunch the editor.
Never registered it? claude mcp add sbox-lifeline -- npx -y sbox-mcp-server@2 --lifeline
Tools execute on the editor's main thread, and a modal dialog (save prompt, popup, error dialog) blocks it, queued work is never picked up. Bring the editor window to the foreground and dismiss the dialog; pending work resumes immediately. If no dialog is visible and calls still stall (screenshots especially), suspect a GPU/render stall: restart_editor clears it and your saved scene survives.
take_screenshotalways renders from the scene's Main Camera: one fixed angle (the player's view in play mode). Use screenshot_from / capture_view to frame a target object or point, or screenshot_orbit for several angles in one call, all of them return the PNG inline in the tool result. (frame_cameraonly moves the editor viewport, which the screenshot doesn't use.)
The bridge deliberately refuses scene-mutating commands while the game is playing, mutating the scene during play can corrupt .scene files on save. Stop play first (play_stop or stop_play), make your edits, then start again. Read-only tools, screenshots, and runtime-property tools (set_runtime_property) are safe during play.
The addon ended up in s&box's global addons/ folder, which is built-in only and silently refuses to compile custom C#. The addon must live in your project's Libraries/claudebridge/ folder. Reinstall from the Asset Library.
The Libraries/ file-watcher is unreliable for external edits (copy/sync/git), it often silently ignores the change, and successful compiles log nothing. The dependable loop: sync files → restart_editor → verify which assembly is live via get_bridge_status rather than trusting silence. Project Code/ edits via write_file / create_script still hotload normally.
The experimental runtime ParticleEffect tools (spawn_particle, add_trail, add_beam) don't render through the bridge. Use spawn_vpcf: it plays a compiled .vpcf, the supported visible particle path. Author the effect in s&box's particle editor, then Claude can spawn it.
The project has both a local-dev Libraries/claudebridge/and an asset-library-installed copy claiming the same compiler name. Keep one: either set the local copy's Org to local, or remove the asset-library copy.
get_bridge_status result and get_compile_errors, then open an issue on GitHub or email sboxskins@gmail.com. See also the FAQ.