Probe for an already-running MCP server, then start the scene. Check through the harness first: if tools are available in the session, call — an answer means the server is up. Fall back to curl only if the tools are absent:

curl -s -m 2 http://127.0.0.1:8123/unity-explorer-mcp -X POST \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}'

Two launch paths produce the same server, and you cannot tell them apart from the probe: from the CLI, and the Creator Hub's scene Preview button with the MCP checkbox ticked (it passes to the same preview process). Same endpoint, same tools, same behaviour — a Creator Hub launch is never the reason a connection fails, so recognise it as a normal setup rather than an anomaly to relaunch out of.

Server found (tool answer or result) — launch/kill gate: use the already-running Explorer, or start the scene from scratch with the MCP flag?

No server found — serve the scene and launch the Explorer in one command from the scene folder (keep it running in the background; if something else already holds port 8000, apply the same kill-or-keep question and port overrides as above):

npm install && npm run start -- --mcp

Alternatively the user can launch from the Creator Hub: enable the "Enable MCP Server" checkbox in the scene's preview settings (only shown when the scene's version supports the flag), then hit Preview. Equivalent to the command above in every respect that matters here.

This serves the scene at , auto-launches the installed Decentraland client connected to it with the MCP server enabled (port 8123; picks another and implies — adjust the 8123 URLs in steps 1 and 2 to match), and hot-reloads the scene whenever a source file changes. Useful extra flags: (dev-server port; the launched client follows it automatically), (spawn parcel), , (force a new client instance), (allow concurrent Explorer instances), (serve only, launch nothing). Anything after a second standalone is forwarded verbatim into the Explorer launch as extra parameters, e.g. (npm consumes the first ). If the command rejects as an unknown option, the scene's predates the flag — update , or launch a specific build by hand ("Launching a specific Explorer build manually" in

reference/setup.md

). If the CLI prints "Please download & install the Decentraland Desktop Client" the dev server is fine but no client is installed — install one, or point the launch at a specific build the same way.

A freshly launched Explorer needs the user to log in. The client opens on the auth screen unless a previous session's login is still cached ( only skips it when a valid identity exists — a missing or expired login shows it anyway, and extra instances always ask). Tell the user to log in, then wait — step 3's polling only starts succeeding once they're through, and only then can you continue working on the scene through the MCP server.

Register the MCP server, then confirm its tools are actually bound (default port 8123). Registration and binding are two different things — you need both.

claude mcp add --transport http --scope user explorer http://127.0.0.1:8123/unity-explorer-mcp

Errors with "already exists in local config" if a previous session registered it — that's fine and expected; registration is persistent config, nothing to do.

This command can hang with no output in non-terminal harnesses (observed in the Claude Code VS Code extension: >2 min, no result, no error). Run it with a short timeout — — and read a hang as probably already registered, not as a failure: registration persists across sessions, so a prior session's still counts. Don't retry it; confirm the endpoint with the step 1 probe instead and move on to the bind gate.

MANDATORY — bind gate: if you launched the Explorer yourself in this session, STOP here as soon as the readiness probe answers, and do NOT start the iteration loop over curl. Claude Code opens its MCP connections once, at session startup, and this server lives inside the Explorer process — so a session that started before the Explorer was up has already failed its one connection attempt, and tools will never appear on their own. Mid-session, only an explicit reconnect re-binds them; alternatively, starting a fresh Claude session while the Explorer keeps running binds them automatically at that session's startup. Both are user actions: there is nothing you can run instead, so ask rather than trying to engineer around it.

Open with the situation — "the Explorer is up, but this Claude session started before it, so the native MCP tools aren't bound" — then offer three paths, best first, with the fallback's costs stated before they can land in it:

Use if your client has it, one option each; label the second "Restart session / new tab (Explorer stays up)" so it can't be misread as closing the Explorer. Otherwise put the same three in plain text and close with "Which do you prefer?".

You may only move past this step in one of these three states — no fourth reading exists, and a subagent can only ever be in the first:

The probe in step 1 is the only curl call you make before this gate. Getting an answer out of it proves the Explorer is up — which is the trigger to ask, not permission to continue.

Mention the prevention once, not every session: starting the Explorer before Claude Code — or simply leaving it running between sessions — skips this gate entirely.

Not running in Claude Code? and are Claude Code commands — for Cursor, Cline, or a custom SDK harness, the connection details and config shapes are in

reference/setup.md

. The Claude Code VS Code extension and the Creator Hub's embedded chat are Claude Code: they take the commands above, with the harness differences noted in the bind gate.

Wait for the world to load: poll until is false and the scene reports .