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.