wehub-resource-sync
83 lines
2.9 KiB
Markdown
83 lines
2.9 KiB
Markdown
---
|
|
id: multi-instance
|
|
slug: /guides/multi-instance
|
|
title: Multi-Instance Routing
|
|
sidebar_label: Multi-Instance Routing
|
|
description: Drive several Unity Editors from a single MCP session with set_active_instance and per-call routing.
|
|
---
|
|
|
|
# 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.
|
|
|
|
## Related reference
|
|
|
|
- [`set_active_instance`](/reference/tools/core/set_active_instance) — full tool reference
|
|
- [`unity_instances` resource](/reference/resources) — discovery surface
|