ContextQMD
Back to Unity Mcp

Multi-Instance Routing

website/docs/guides/multi-instance.md

9.7.12.7 KB
Original Source

Multi-Instance Routing

You can have several Unity Editors open at once and aim a single MCP session at any of them.

When this comes up

  • You're refactoring a shared package and need to test the same change in two projects
  • You're comparing behavior between Unity LTS and Unity 6
  • You have a runtime project + a tooling project both connected
  • You're driving a CI fixture project alongside your day-to-day work

How instances are identified

Each connected Unity Editor advertises a stable ID of the form Name@hash, where:

  • Name is the project's productName from Player Settings
  • hash is a stable 8-character hash derived from the project path

Example: MyGame@a1b2c3d4.

You can also reference an instance by:

  • Hash prefix (e.g. a1b if it's unambiguous)
  • Port number — stdio transport only

Discovering instances

Read the resource:

mcpforunity://instances

It returns the list of currently connected Editors with their Name@hash, project path, transport, and port. Most MCP clients expose this as the unity_instances resource.

Setting the active instance for the session

set_active_instance(instance="MyGame@a1b2c3d4")

Once set, every subsequent tool call in the session routes to that instance until you change it. This is the most common pattern: choose once, then prompt normally.

You can also use:

set_active_instance(instance="a1b")         # hash prefix
set_active_instance(instance="6401")        # port number (stdio only)

Routing a single call without changing the session default

Pass unity_instance on the individual tool call:

manage_scene(action="get_hierarchy", unity_instance="MyGame@a1b2c3d4")

This is useful for comparing two projects in the same prompt — e.g., "Read the same script from both projects and tell me what differs."

The server accepts the same value formats as set_active_instance: Name@hash, hash prefix, or (stdio) port number.

What happens with no active instance

  • One Unity Editor connected → it's used automatically.
  • Multiple Editors connected and no active set → the server errors with the available instance list. Call set_active_instance and retry.

HTTP vs stdio differences

  • HTTP: instance state is keyed per-session by client_id, so two MCP clients can target different Editors at the same time on the same Python server.
  • Stdio: port-number shorthand works because there's a separate Python process per client. HTTP shares one process and uses Name@hash exclusively.