Unity 6.3 LTS keeps crashing when MCP tools are being called

[ValiDraganescu]

The Editor crashes randomly when mcp tools are being called (probably they have incorrect values or something). I am using Claude Code but had the same issues earlier with Windsurf/Antigravity

The mcp server shows no errors

2025-12-27 12:20:11,999 - mcp.server.streamable_http_manager - INFO - Created new transport with session ID: 3af34d3cc794418c8e14fbe8673567fd
INFO:     ::1:60878 - "POST /mcp HTTP/1.1" 200 OK
INFO:     ::1:60878 - "POST /mcp HTTP/1.1" 202 Accepted
INFO:     ::1:60878 - "GET /mcp HTTP/1.1" 200 OK
INFO:     ::1:60908 - "POST /mcp HTTP/1.1" 200 OK
INFO:     ::1:60910 - "POST /mcp HTTP/1.1" 200 OK
INFO:     ::1:60913 - "POST /mcp HTTP/1.1" 200 OK
2025-12-27 12:20:35,928 - mcp.server.streamable_http_manager - INFO - Created new transport with session ID: 9677297299d446cfaf42755df5784d0e
INFO:     ::1:61001 - "POST /mcp HTTP/1.1" 200 OK
INFO:     ::1:61001 - "POST /mcp HTTP/1.1" 202 Accepted
INFO:     ::1:61001 - "GET /mcp HTTP/1.1" 200 OK
INFO:     ('::1', 61019) - "WebSocket /hub/plugin" [accepted]
INFO:     connection open
INFO:     ::1:61261 - "POST /mcp HTTP/1.1" 200 OK
INFO:     ::1:61261 - "POST /mcp HTTP/1.1" 200 OK
INFO:     ::1:61307 - "POST /mcp HTTP/1.1" 200 OK
INFO:     ::1:61348 - "POST /mcp HTTP/1.1" 200 OK
INFO:     ::1:61381 - "POST /mcp HTTP/1.1" 200 OK
INFO:     ::1:61381 - "POST /mcp HTTP/1.1" 200 OK

Claude code shows MCP response with "Python error managing GameObject: " with no meaningful error message

  ⎿  {                                     
       "success": true,
       "message": "Found 1 GameObject(s).",
     … +63 lines (ctrl+o to expand)

⏺ UnityMCP - manage_scene (MCP)(action: "get_hierarchy")
  ⎿  {                                                           
       "success": true,
       "message": "Retrieved hierarchy for scene 'SampleScene'.",
     … +3696 lines (ctrl+o to expand)

⏺ I can see the player has a child model HumanMale_Character_FREE. Let me check its Animator component:

⏺ UnityMCP - manage_gameobject (MCP)(action: "get_component", target: "HumanMale_Character_FREE", component_name: "Animator")
  ⎿  {                                                
       "success": false,
       "message": "Python error managing GameObject: "
     }

⏺ UnityMCP - manage_gameobject (MCP)(action: "get_components", target: "HumanMale_Character_FREE")
  ⎿  {                                                                                        
       "success": false,
       "message": "Python error managing GameObject: No Unity plugins are currently connected"
     }

⏺ Unity connection dropped. Let me check your existing PlayerAnimator controller to see what parameters it has:

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Possible Duplicates

• Unity Editor crashing #238

Related Issues

• Claude crashing while examining Unity project #168
• Antigravity mcp error - Failure in MCP tool execution: connection closed: calling "tools/call": client is closing: standalone SSE stream #446
• The tool interface does not load. #445
• Claude having issues editing scripts #183
• initialization timeout #359
• There are a large number of parameters of invalid types #42

🔗 Related PRs

#266 - Fix: Unity Editor reload crash + debug-noise reduction [merged]

👤 Suggested Assignees

• samueltpark
• gravitydeepimpactsun
• mhndgx
• baltimortv2
• tribbloid

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Approach

Ticket Summary

Unity Editor crashes when MCP tools attempt to serialize Animator components via reflection. The crash occurs without meaningful error messages, and the Python server only returns empty error strings like "Python error managing GameObject: ". The root cause is that Animator component properties are unsafe to access via reflection during serialization, causing Unity's engine to crash.

Observations

Codebase Summary

This is a Unity MCP (Model Context Protocol) integration with a Python server and Unity C# client that communicate via WebSocket. The Python server (Server/src/) implements MCP tools for GameObject manipulation, while the Unity client (MCPForUnity/Editor/) handles command execution and serializes component data using reflection. The serialization system has special handling for crash-prone components like Transform and Camera, but lacks protection for Animator. Error handling follows a consistent pattern across both layers, with try-catch blocks converting exceptions to structured JSON responses.

Assumptions

Assumption 1: How much Animator data should users be able to access?

Options Considered:

• Skip Animator entirely: Add Animator to the component type blacklist, preventing all serialization attempts
• Curated safe property list: Implement Animator-specific handling similar to Transform/Camera with only safe properties exposed
• Skip by default with opt-in flag: Allow advanced users to enable Animator serialization with warnings

Chosen Option: Skip Animator entirely

Rationale: This is the simplest solution that follows Unity best practices (web search confirms Animator properties accessing engine-managed data should not be called during serialization), eliminates all crash risk, and aligns with the existing component filtering pattern. Users can still check if Animator exists on a GameObject; they just won't see its internal property values. If users need basic Animator data in the future, we can add a curated safe-list as a follow-up enhancement.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Prevent Unity Crashes by Filtering Animator Components

This phase modifies the Unity serialization layer to skip Animator components entirely, preventing the reflection-based property access that causes crashes. This is the critical fix that directly resolves the crash issue.

Task 1: Add Animator to Component Type Blacklist

Update the component serialization logic to explicitly skip Animator components before attempting property reflection.

• Modify MCPForUnity/Editor/Helpers/GameObjectSerializer.cs in the GetComponentData() method to add a check for Animator component type before the existing Transform/Camera special cases
• Add early return when component type is Animator, returning a minimal object indicating the component exists but data is unavailable for safety reasons
• Include a descriptive message like "Animator component skipped - properties cannot be safely serialized via reflection"
• Follow the same pattern as the Transform/Camera type checks (using component is Animator or component.GetType() == typeof(Animator))

Task 2: Handle Animator in Component Iteration

Ensure the component iteration logic properly handles Animator components when collecting all components from a GameObject.

• Update MCPForUnity/Editor/Services/ManageGameObject.cs in the GetComponentsFromTarget() method to check component type before calling GameObjectSerializer.GetComponentData()
• Add Animator to any component type filtering that occurs during iteration
• Ensure the error handling wrapper continues to work correctly when Animator is present but skipped
• Maintain the existing pattern of including a placeholder entry rather than silently omitting the component

🤖 Prompt for AI agents

Modify Unity serialization to skip Animator components and prevent crashes.

In `MCPForUnity/Editor/Helpers/GameObjectSerializer.cs`:
- Add Animator type check in `GetComponentData()` before existing
Transform/Camera checks
- Return early with minimal object indicating component exists but is skipped
for safety
- Include message: "Animator component skipped - properties cannot be safely
serialized via reflection"

In `MCPForUnity/Editor/Services/ManageGameObject.cs`:
- Add Animator check in `GetComponentsFromTarget()` before calling
`GameObjectSerializer.GetComponentData()`
- Ensure placeholder entry is included for skipped Animator components
- Maintain existing error handling patterns

Phase 2: Improve Error Diagnostics in Python Server

This phase enhances error handling to provide meaningful error messages when problems occur, addressing the empty error string issue. While this doesn't prevent crashes, it significantly improves debuggability for all error scenarios.

Task 1: Preserve Full Exception Information in Tool Error Handling

Update exception handling in MCP tool implementations to capture and log full tracebacks before returning error responses.

• Modify Server/src/services/tools/manage_gameobject.py exception handler (lines 239-240) to log the full exception with traceback using logger.exception() or logger.error(..., exc_info=True) before constructing the error response
• Update the error message format to include both str(e) and the exception type (e.g., f"Python error managing GameObject: {type(e).__name__}: {e!s}")
• Import the logging module if not already present and use the appropriate logger instance
• Apply the same pattern to other tool files following the consistent error handling approach (manage_editor.py, manage_shader.py, manage_scene.py, manage_script.py, manage_prefabs.py)

Task 2: Enhance WebSocket Error Reporting

Improve error propagation through the WebSocket communication layer to ensure Unity crashes and connection drops are properly detected and reported.

• Review Server/src/transport/plugin_hub.py in the on_disconnect() and command execution handlers to ensure disconnections during command execution result in clear timeout errors rather than empty messages
• Add debug logging when commands timeout or connections drop mid-execution to aid troubleshooting
• Ensure the timeout error messages in the asyncio.wait_for() wrapper include the command_id and action being performed
• Consider adding connection health logging when WebSocket state changes occur during active commands

🤖 Prompt for AI agents

Enhance error handling and logging across Python server to provide meaningful
error messages.

In `Server/src/services/tools/manage_gameobject.py` and other tool files:
- Update exception handlers to log full tracebacks using `logger.exception()` or
`logger.error(..., exc_info=True)`
- Change error message format to include exception type: `f"Python error
managing GameObject: {type(e).__name__}: {e!s}"`
- Apply pattern to all tool files: `manage_editor.py`, `manage_shader.py`,
`manage_scene.py`, `manage_script.py`, `manage_prefabs.py`

In `Server/src/transport/plugin_hub.py`:
- Ensure `on_disconnect()` and command execution handlers produce clear timeout
errors
- Add debug logging for command timeouts and mid-execution disconnections
- Include command_id and action in timeout error messages from
`asyncio.wait_for()` wrapper
- Add connection health logging for WebSocket state changes during active
commands

Phase 3: Documentation and Future Enhancements

This phase documents the changes and provides guidance for future improvements if users need more Animator data.

Task 1: Document Animator Serialization Limitation

Add code comments and potentially user-facing documentation explaining why Animator is skipped.

• Add XML documentation comments in GameObjectSerializer.cs explaining the Animator exclusion and referencing Unity's serialization restrictions
• Document the limitation in any user-facing API documentation or README files that describe the get_component and get_components actions
• Include a comment referencing the Unity issue tracker and documentation about unsafe Animator property access during serialization

Task 2: Create Path for Future Safe Animator Properties

Set up the structure to allow adding safe Animator properties in the future if needed.

• Add a TODO comment or GitHub issue describing how to implement a curated safe property list for Animator (similar to Camera's implementation)
• Document which Animator properties are known to be safe (e.g., enabled, speed, cullingMode) versus unsafe (e.g., runtimeAnimatorController, avatar, layer/parameter queries)
• Note that any future safe-list implementation should wrap each property access in its own try-catch block to isolate failures

🤖 Prompt for AI agents

Document Animator serialization limitation and create path for future
enhancements.

In `GameObjectSerializer.cs`:
- Add XML documentation comments explaining Animator exclusion and Unity
serialization restrictions
- Reference Unity documentation about unsafe Animator property access

In user-facing documentation:
- Document limitation in README or API docs for `get_component` and
`get_components` actions

For future enhancements:
- Add TODO comment or GitHub issue for implementing curated safe property list
(similar to Camera)
- Document safe properties: `enabled`, `speed`, `cullingMode`
- Document unsafe properties: `runtimeAnimatorController`, `avatar`,
layer/parameter queries
- Note that future implementation should wrap each property in try-catch blocks

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Modify Unity serialization to skip Animator components and prevent crashes.

In `MCPForUnity/Editor/Helpers/GameObjectSerializer.cs`:
- Add Animator type check in `GetComponentData()` before existing
Transform/Camera checks
- Return early with minimal object indicating component exists but is skipped
for safety
- Include message: "Animator component skipped - properties cannot be safely
serialized via reflection"

In `MCPForUnity/Editor/Services/ManageGameObject.cs`:
- Add Animator check in `GetComponentsFromTarget()` before calling
`GameObjectSerializer.GetComponentData()`
- Ensure placeholder entry is included for skipped Animator components
- Maintain existing error handling patterns
===============================================================================

Task: 2

Enhance error handling and logging across Python server to provide meaningful
error messages.

In `Server/src/services/tools/manage_gameobject.py` and other tool files:
- Update exception handlers to log full tracebacks using `logger.exception()` or
`logger.error(..., exc_info=True)`
- Change error message format to include exception type: `f"Python error
managing GameObject: {type(e).__name__}: {e!s}"`
- Apply pattern to all tool files: `manage_editor.py`, `manage_shader.py`,
`manage_scene.py`, `manage_script.py`, `manage_prefabs.py`

In `Server/src/transport/plugin_hub.py`:
- Ensure `on_disconnect()` and command execution handlers produce clear timeout
errors
- Add debug logging for command timeouts and mid-execution disconnections
- Include command_id and action in timeout error messages from
`asyncio.wait_for()` wrapper
- Add connection health logging for WebSocket state changes during active
commands
===============================================================================

Task: 3

Document Animator serialization limitation and create path for future
enhancements.

In `GameObjectSerializer.cs`:
- Add XML documentation comments explaining Animator exclusion and Unity
serialization restrictions
- Reference Unity documentation about unsafe Animator property access

In user-facing documentation:
- Document limitation in README or API docs for `get_component` and
`get_components` actions

For future enhancements:
- Add TODO comment or GitHub issue for implementing curated safe property list
(similar to Camera)
- Document safe properties: `enabled`, `speed`, `cullingMode`
- Document unsafe properties: `runtimeAnimatorController`, `avatar`,
layer/parameter queries
- Note that future implementation should wrap each property in try-catch blocks

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[dsarno]

Hi @ValiDraganescu -- thanks for the report. I've hard a hard time reproducing the crash you're talking about in Unity 6.3 on Windows, getting component / gameobject data about animators or large hierarchies. If you're able to give more detail on the unity scene you're getting the crashes with -- how many objects in the hierarchy. And how many components, with how much serialized data, on the HumanMale_Character_FREE.

It doesn't seem to be a global problem with the Unity MCP and Unity 6.3, or even with the get_components or get_hierarchy actions -- although both of those definitely need to be refactored to handle large payloads. They were written early in the history of the unity_mcp and not optimized. (Referenced in #455 -- probably the same issue).

[dsarno]

Should be fixed in latest release 8.4.0. Please let us know if you continue seeing this type of issue.