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

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, 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 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 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.

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 (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.

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

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 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, which constructs candidate identifiers and matches them against the registry
• The plugin registry in 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}