# How to Debug Unity MCP: A Complete Guide for Python Server and Unity Editor

> Debug Unity MCP effectively by inspecting the Python server with debug_request_context and the Unity Editor using McpLog. Get our complete guide now.

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

---

**Debugging Unity MCP requires inspecting both the Python server using the `debug_request_context` tool and the Unity Editor through the `McpLog` system with colored `MCP-FOR-UNITY` tags.**

Unity MCP is a two-part system consisting of a Python server that receives MCP requests and a Unity Editor plugin that executes the requested actions. When troubleshooting failures in the CoplayDev/unity-mcp repository, you need visibility into both the server-side request context and the Unity-side log output to trace the full execution flow.

## Understanding the Unity MCP Architecture

Unity MCP operates across two distinct layers that must communicate properly for tools to function.

The **Python server** handles incoming MCP requests and maintains session state through FastMCP's request context. According to the source code in [`Server/src/services/tools/debug_request_context.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/services/tools/debug_request_context.py), the server exposes internal diagnostics including the current working directory, argv, and active Unity instance mappings.

The **Unity Editor** executes the actual game engine operations through the plugin hub. The Unity side uses `McpLog` (located in [`MCPForUnity/Editor/Helpers/McpLog.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/MCPForUnity/Editor/Helpers/McpLog.cs)) to output prefixed log lines that you can filter in the Console window.

## Enabling Debug Logging in the Unity Editor

Before tracing issues, you must enable debug-level messages on the Unity side. The `McpLog` system suppresses debug output unless explicitly enabled.

You can activate debug logging through three methods:

- **Via the MCP UI** – Navigate to *Window → MCP for Unity → Configure All Detected Clients* and enable **Show debug logs**.
- **Programmatically** – Call `McpLog.SetDebugLoggingEnabled(true)` from any Editor script.
- **Persisted preference** – The flag stores in `EditorPrefs` under the key `EditorPrefKeys.DebugLogs` (defined in [`MCPForUnity/Editor/Constants/EditorPrefKeys.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/MCPForUnity/Editor/Constants/EditorPrefKeys.cs)).

When enabled, every call to `McpLog.Debug` writes a formatted line to the Unity Console:

```

<b><color=#6AA84F>MCP-FOR-UNITY</color></b>: <your message>

```

This color-coded prefix makes it easy to filter the Console for MCP-specific messages.

## Using the debug_request_context Tool

The server exposes a built-in diagnostic tool called `debug_request_context` that dumps the current request context and middleware state.

Run the tool from your terminal:

```bash
unity-mcp core debug_request_context

```

The tool returns a JSON payload containing server diagnostics, request context fields, and session state:

```json
{
  "success": true,
  "data": {
    "server": {
      "version": "10.0.0",
      "cwd": "/path/to/project",
      "argv": ["uv", "run", "python", "-m", "mcp"]
    },
    "request_context": {
      "client_id": "claude-desktop",
      "session_id": "8f2a1c…",
      "meta": { }
    },
    "session_state": {
      "active_instance": "UnityInstance(…)",
      "plugin_hub_configured": true,
      "middleware_id": 140592334208784
    }
  }
}

```

According to the implementation in [`Server/src/services/tools/debug_request_context.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/services/tools/debug_request_context.py), this tool pulls the request context from FastMCP (`ctx.request_context`), falls back to top-level `ctx.client_id`/`ctx.session_id`, and reports the middleware's active Unity instance via `transport.unity_instance_middleware`.

## Diagnosing Common Connection Issues

When debugging Unity MCP failures, match your symptoms to the appropriate diagnostic layer:

| Symptom | Likely Cause | Debug Steps |
|---------|--------------|-------------|
| **No tool response** with "bridge unreachable" error | Server not running or wrong transport mode | Verify the server process with `ps` or check `uv run python -m mcp` console output |
| **Unity actions silently fail** | Debug logging disabled, hiding error messages | Enable debug logs via `McpLog.SetDebugLoggingEnabled(true)` and watch for `MCP-FOR-UNITY` warnings |
| **Wrong Unity instance receives commands** | Multiple Unity editors attached with wrong session ID | Run `debug_request_context` and inspect `"active_instance"`; compare IDs with expected Unity windows |
| **PluginHub not configured** | Bridge initialization error (missing WebSocket route) | Check `debug_request_context` for `"plugin_hub_configured": false` and review Unity logs for `PluginHub` init errors |

The `transport.unity_instance_middleware` module stores per-session middleware state, and its `get_active_instance` method is called by `debug_request_context` to expose which Unity instance is currently targeted.

## Key Source Files for Debugging

When tracing issues through the CoplayDev/unity-mcp codebase, reference these specific files:

- **[`MCPForUnity/Editor/Helpers/McpLog.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/MCPForUnity/Editor/Helpers/McpLog.cs)** – Centralized Unity-side logger with debug gating and colored console output
- **[`Server/src/services/tools/debug_request_context.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/services/tools/debug_request_context.py)** – Exposes FastMCP request context and middleware state as a JSON tool
- **[`Server/src/transport/unity_instance_middleware.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/transport/unity_instance_middleware.py)** – Stores per-session Unity instance information used by the debug tool
- **[`Server/src/transport/plugin_hub.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/transport/plugin_hub.py)** – Manages the WebSocket hub; `PluginHub.is_configured()` is reported by `debug_request_context`
- **[`MCPForUnity/Editor/Constants/EditorPrefKeys.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/MCPForUnity/Editor/Constants/EditorPrefKeys.cs)** – Defines the `DebugLogs` preference key for persistent settings

## Summary

- **Unity MCP debugging requires dual visibility**: Inspect the Python server with `debug_request_context` and the Unity Editor with `McpLog` output.
- **Enable debug logs first**: Use `McpLog.SetDebugLoggingEnabled(true)` or the UI toggle to reveal `MCP-FOR-UNITY` prefixed messages in the Unity Console.
- **Verify the bridge state**: Run `unity-mcp core debug_request_context` to check `plugin_hub_configured` and `active_instance` values.
- **Check specific files**: Reference [`debug_request_context.py`](https://github.com/CoplayDev/unity-mcp/blob/main/debug_request_context.py) for server diagnostics and [`McpLog.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/McpLog.cs) for Unity-side logging implementation.

## Frequently Asked Questions

### How do I check which Unity instance is currently active?

Run the `debug_request_context` tool and examine the `session_state.active_instance` field in the JSON output. This value is retrieved from `transport.unity_instance_middleware` and shows which Unity Editor window is receiving MCP commands. If you have multiple Unity instances open, compare this ID against the window titles or process IDs to ensure you're targeting the correct project.

### Why are my Unity MCP commands failing silently?

Silent failures usually indicate that debug logging is disabled in the Unity Editor. The `McpLog` system filters debug messages unless you explicitly enable them via *Window → MCP for Unity → Configure All Detected Clients* or by calling `McpLog.SetDebugLoggingEnabled(true)`. Once enabled, check the Unity Console for `MCP-FOR-UNITY` tagged error messages that explain the failure.

### What does "plugin_hub_configured": false mean in the debug output?

This status indicates that the WebSocket bridge between the Python server and Unity Editor has not initialized properly. According to [`Server/src/transport/plugin_hub.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/transport/plugin_hub.py), the `PluginHub.is_configured()` method returns false when the hub fails to start, often due to port conflicts or missing WebSocket routes. Check the Unity Editor logs for `PluginHub` initialization errors and ensure your Unity project has the MCP plugin properly installed and enabled.

### Can I enable Unity MCP debugging from a script?

Yes, you can programmatically enable debug logging from any Editor script by importing `McpLog` and calling `SetDebugLoggingEnabled(true)`. This sets the `EditorPrefKeys.DebugLogs` preference key in Unity's `EditorPrefs`, persisting the setting across sessions. You can also create a menu item for quick toggling during development sessions.