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

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

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:

unity-mcp core debug_request_context

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

{
  "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, 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 – Centralized Unity-side logger with debug gating and colored console output
• 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 – Stores per-session Unity instance information used by the debug tool
• Server/src/transport/plugin_hub.py – Manages the WebSocket hub; PluginHub.is_configured() is reported by debug_request_context
• 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 for server diagnostics and 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, 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.

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