# Troubleshooting

## Server Not Starting

* Check the Unity Console for `[MCP]` log entries
* Ensure port 18711 is not blocked by a firewall or another application
* Toggle **Debug** mode via the toolbar popup for verbose logging
* Try clicking **Restart Python Server** in the setup popup

## Tools Not Discovered

* Ensure methods are `public static string` with the `[McpTool]` attribute
* Check for compile errors in the Unity Console — tools are only registered after successful compilation
* Click **Refresh** in the toolbar popup to force re-discovery
* Verify the tool class is in an assembly that references `realvirtual.MCP`

## Connection Issues

* The brain icon should be **green** when a client is connected
* **Yellow** means the server is running but no client has connected yet
* Check that your MCP client configuration points to the correct Python server path
* Ensure **git** is installed and available in PATH

## Timeouts During Play Mode

* Unity throttles editor updates during play mode — tool calls may be slower
* `component_set` operations may not work during play mode
* `component_get` can timeout if the Unity main thread is busy with simulation
* Consider stopping simulation before performing editor operations

## Python Server Issues

* Click **Update Python Server (git pull)** to get the latest version
* Click **Open MCP Folder** to inspect the Python server files
* The Python server includes an embedded Python 3.12 runtime — no system Python is required
* Check the Python server console output for connection errors

## Port Conflicts

The MCP Server uses port 18711 by default. If the port is busy, it auto-increments to find a free port. The actual port is shown in the toolbar popup. Ensure your MCP client configuration matches the displayed port.

## Multi-Instance Setup

Each Unity instance gets a unique instance hash (shown as `#xxxxxxxx` in the toolbar). When running multiple Unity projects simultaneously, each instance runs its own MCP server on a different port. The Python server uses the instance hash to connect to the correct Unity instance.