> For the complete documentation index, see [llms.txt](https://doc.realvirtual.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.realvirtual.io/extensions/mcp-server/troubleshooting.md).

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://doc.realvirtual.io/extensions/mcp-server/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.