# Targeting Specific Unity Instances by Name, Hash, or Port in MCP

> Target specific Unity instances in MCP by name, hash, or port. Unity instance middleware and registry efficiently resolve your target for seamless development. Learn how to connect precisely.

- Repository: [Coplay/unity-mcp](https://github.com/CoplayDev/unity-mcp)
- Tags: how-to-guide
- Published: 2026-07-06

---

**You can target specific Unity editors in MCP using the full `Name@hash` identifier, just the hash fragment, or the stdio bridge port, with resolution handled by the unity instance middleware and registry.**

The **unity-mcp** project enables the Model Context Protocol (MCP) to communicate with multiple simultaneous Unity editor instances. Each running Unity process advertises a unique **instance identifier** that the MCP server uses to route tool calls and resource requests to the correct editor.

## Understanding Unity Instance Identifiers

When multiple Unity editors connect to the MCP server, each instance registers with a composite identifier that combines human-readable metadata with a unique process hash.

### The Name@hash Format

The canonical format for identifying a Unity instance is **`Name@hash`**, where `Name` represents the human-readable project name and `hash` is a short unique identifier for the specific Unity process. According to the source code in [`Server/src/transport/unity_instance_middleware.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/transport/unity_instance_middleware.py), the middleware accepts three input forms:

- **Full identifier**: The complete `Name@hash` string (e.g., `DemoProject@a1b2c3`)
- **Hash prefix**: Just the hash portion (e.g., `a1b2c3`)
- **Bare port number**: The TCP port when operating in stdio mode (e.g., `6401`)

The resolution logic builds candidate identifiers using `f"{project}@{hash_value}"` patterns, extracting the hash via `hash_value = getattr(session_info, "hash", None)` as implemented in the middleware's session handling code.

### Hash-Only and Port-Based Targeting

In **local mode**, the server maintains a hash-only mapping (`_hash_to_session`) that allows you to target instances using just the hash fragment. In **stdio mode**, the middleware can resolve instances by the TCP port number that the stdio bridge writes to its status file on launch.

## How Instance Resolution Works

The unity-mcp server relies on two critical components to resolve instance identifiers to active sessions.

### Unity Instance Middleware Resolution

The file **[`Server/src/transport/unity_instance_middleware.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/transport/unity_instance_middleware.py)** contains the core resolution logic. When a request arrives, the middleware:

1. Extracts the hash from session metadata
2. Constructs candidate `Name@hash` combinations
3. Matches against registered instances using the `get_session_id_by_hash` helper

The middleware also provides the `mcpforunity://instances` endpoint for client discovery, returning a JSON array of available instance strings like `["DemoProject@a1b2c3", "GameDemo@d4e5f6"]`.

### Plugin Registry Mapping

The **[`Server/src/transport/plugin_registry.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/transport/plugin_registry.py)** maintains the underlying registry that maps identifiers to concrete session IDs. It stores:

- **`_hash_to_session`**: A dictionary mapping hash strings to session IDs for local mode
- **`(user_id, project_hash)` tuples**: Composite keys for remote-hosted mode

The `get_session_id_by_hash` method (lines 152-160) performs the final resolution, taking either a bare hash or a `Name@hash` string and returning the session ID that subsequent tool calls will use.

## Setting the Active Instance

Before issuing tool calls when multiple instances are connected, you **must** explicitly set the active instance using the **`set_active_instance`** tool. This tool persists your selection in the server's session state.

```python
from mcp import MCPClient

client = MCPClient()

# Target by full identifier

client.tool("set_active_instance", {"instance_id": "DemoProject@a1b2c3"})

# Or target by hash only

client.tool("set_active_instance", {"instance_id": "a1b2c3"})

# Or target by port (stdio mode)

client.tool("set_active_instance", {"instance_id": "6401"})

```

The implementation in [`Server/src/services/tools/set_active_instance.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/services/tools/set_active_instance.py) (lines 22-51) validates the instance ID against the registry and updates the session's active instance marker.

## Discovering Available Unity Instances

To enumerate running Unity editors, query the read-only resource at **`mcpforunity://instances`**. This returns the list of registered `Name@hash` strings currently connected to the server.

```python
from mcp import MCPClient

client = MCPClient()

# Discover all available instances

instances = client.resource("instances")
print(instances)  # Output: ["DemoProject@a1b2c3", "GameDemo@d4e5f6"]

```

## Complete Workflow Example

Follow this pattern to reliably target a specific Unity process:

1. **Discover** available instances using the instances resource
2. **Select** the target instance using `set_active_instance` with either the full `Name@hash`, hash fragment, or port
3. **Execute** tools, which are automatically routed to the selected instance

```python
from mcp import MCPClient

client = MCPClient()

# Step 1: Discover

instances = client.resource("instances")
print(f"Available instances: {instances}")

# Step 2: Select (using hash only)

client.tool("set_active_instance", {"instance_id": "a1b2c3"})

# Step 3: Execute - automatically routed to the selected Unity editor

result = client.tool("manage_material", {
    "action": "create", 
    "name": "MyMaterial"
})
print(result)

```

If you omit the selection step while multiple instances are running, the server returns an error message: **"Multiple instances connected; call set_active_instance first."** This validation check appears in [`Server/src/main.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/main.py) at line 308.

## Summary

- Unity-mcp supports three identifier formats: full `Name@hash`, hash-only, or bare port numbers in stdio mode
- Resolution logic resides in [`Server/src/transport/unity_instance_middleware.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/transport/unity_instance_middleware.py), which constructs candidate identifiers and matches them against the registry
- The plugin registry in [`Server/src/transport/plugin_registry.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/transport/plugin_registry.py) maintains `_hash_to_session` mappings for local mode and composite keys for remote mode
- You must call the `set_active_instance` tool before issuing commands when multiple Unity editors are connected
- Query `mcpforunity://instances` to discover available targets programmatically

## Frequently Asked Questions

### What is the difference between Name@hash and hash-only targeting?

**Name@hash** provides the complete identifier including the human-readable project name, while **hash-only** targeting uses just the unique process hash. The server accepts both formats because the `get_session_id_by_hash` function in the plugin registry can resolve partial matches. Hash-only targeting is particularly useful in stdio mode where you might only know the hash from status files.

### How do I find the port number for stdio mode?

When Unity launches in stdio mode, it writes a status file containing the TCP port that the bridge is listening on. The unity instance middleware scans these status files to match bare port numbers (like `6401`) to their corresponding `Name@hash` entries. You can also discover active ports by querying the `mcpforunity://instances` resource, which lists all connected instances regardless of connection mode.

### What happens if I don't set an active instance with multiple Unity editors running?

The server returns an explicit error: **"Multiple instances connected; call set_active_instance first."** This safeguard, implemented in [`Server/src/main.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/main.py), prevents ambiguous tool calls from being routed to the wrong Unity process. When only one instance is connected, the server can infer the target, but explicitly setting the instance is still recommended for clarity.

### Can I switch between instances without restarting the MCP client?

Yes. You can call `set_active_instance` multiple times within the same session to switch between different Unity editors. Each call updates the session state maintained by the unity instance middleware, causing subsequent tool calls to route to the newly selected instance. This allows you to work with multiple Unity projects sequentially without reinitializing your MCP connection.