Assets/Plugins/UnityMCP/Runtime: The Core Runtime Bridge for Unity MCP

The Assets/Plugins/UnityMCP/Runtime/ directory contains the essential C# assembly that enables Unity projects to communicate with the Python MCP server through JSON-RPC calls, version compatibility shims, and Unity type serialization.

The unity-mcp repository by CoplayDev provides a Model Context Protocol (MCP) integration for Unity, allowing AI assistants to control the editor programmatically. At the heart of this integration lies the Assets/Plugins/UnityMCP/Runtime/ folder, which compiles into a runtime assembly that lives inside both the Unity Editor and built players. This directory houses the essential infrastructure that bridges Unity's C# environment with the external Python MCP server.

Core Responsibilities of the Runtime Assembly

The runtime assembly serves as the communication backbone and compatibility layer for the entire MCP for Unity plugin. According to the CoplayDev/unity-mcp source code, the code under Assets/Plugins/UnityMCP/Runtime/ handles four critical functional areas.

Bridge to the MCP Server

The runtime code establishes the JSON-RPC communication channel that allows the Python server to send commands to Unity. In Assets/Plugins/UnityMCP/Runtime/AssemblyInfo.cs, the assembly metadata defines the entry points where the MCP server marshals parameters and forwards them to appropriate C# tool handlers. This enables external processes to execute commands like send_with_unity_instance directly within the Unity environment.

Version Compatibility Shims

Unity's API evolves rapidly between versions 2021 and 2026, requiring abstraction layers to maintain backward compatibility. The runtime folder contains several shim files that hide version-specific API changes:

• UnityCompatShims.cs: A documentation marker cataloging all compatibility shims
• UnityFindObjectsCompat.cs: Handles Object.FindObjectsByType versus the older Object.FindObjectsOfType API differences
• UnityPhysicsCompat.cs: Abstracts physics API changes such as Physics.RaycastAll variations
• UnityObjectIdCompat.cs: Manages object-ID handling inconsistencies across Unity releases
• UnityAssembliesCompat.cs: Addresses assembly loading changes between Unity versions

Serialization for Unity Types

Native Unity structures like Vector3, Matrix4x4, and Color require conversion to JSON for transmission over the MCP protocol. The UnityTypeConverters.cs file in Assets/Plugins/UnityMCP/Runtime/Serialization/ provides static methods to convert these Unity-specific types into protocol-friendly formats and back again.

Utility Services

The runtime includes helper utilities that must execute within the Unity runtime context. The ScreenshotUtility.cs file provides methods to capture the editor or game view as PNG bytes, while other helpers manage asset-path resolution and file system operations that work across different Unity versions.

Key Source Files in the Runtime Directory

Understanding the specific files within Assets/Plugins/UnityMCP/Runtime/ helps developers extend or debug the MCP integration:

• AssemblyInfo.cs: Defines assembly attributes, version metadata, and GUIDs required by Unity's compilation pipeline
• UnityCompatShims.cs: Documents the shim architecture and explains when new compatibility layers are necessary
• UnityTypeConverters.cs: Implements JSON serialization for Unity mathematics structs and color types
• ScreenshotUtility.cs: Captures screen data for remote debugging and visual verification

Practical Implementation Examples

The following examples demonstrate how to utilize the runtime components in your Unity MCP implementation:

// Using compatibility shims to find cameras across Unity versions
var cameras = UnityFindObjectsCompat.FindObjectsByType<Camera>(
    FindObjectsSortMode.None, 
    includeInactive: true);

// Converting Unity Matrix4x4 to JSON for MCP transmission
var json = UnityTypeConverters.Matrix4x4ToJson(myMatrix);

// Capturing a screenshot from within the runtime assembly
var pngBytes = ScreenshotUtility.CaptureScreen();

Summary

• The Assets/Plugins/UnityMCP/Runtime/ directory compiles into the core runtime assembly for the MCP for Unity plugin
• It provides the JSON-RPC bridge that enables Python servers to communicate with Unity via AssemblyInfo.cs and related handlers
• Version compatibility shims in files like UnityFindObjectsCompat.cs and UnityPhysicsCompat.cs ensure the plugin works across Unity 2021 through 2026
• UnityTypeConverters.cs handles serialization of native Unity types to JSON for network transmission
• Because the code is pure C# within the Assets folder, developers can inspect, debug, and extend it directly from the Unity Editor

Frequently Asked Questions

What happens if I delete the Assets/Plugins/UnityMCP/Runtime folder?

Deleting this directory removes the core communication layer between Unity and the Python MCP server. The editor tools will lose the ability to execute commands sent from external AI assistants, and built players will lack the serialization utilities required for MCP functionality. The plugin depends entirely on this assembly being present in the compiled project.

Can I modify the compatibility shims for my specific Unity version?

Yes, since the runtime code lives in your Assets folder as standard C# files, you can modify UnityCompatShims.cs and its related files directly. Changes take effect immediately upon Unity recompiling the scripts, allowing you to add custom version-specific handling or extend existing shims like UnityAssembliesCompat.cs to address edge cases in your specific Unity installation.

How does the runtime assembly handle Unity version differences?

The runtime uses conditional compilation and wrapper methods in files like UnityFindObjectsCompat.cs to abstract API differences. For example, when calling FindObjectsByType, the shim automatically selects the correct Unity API based on the current editor version, ensuring consistent behavior across Unity 2021 LTS through Unity 2026 alpha builds without requiring separate code branches in the tool implementations.

Where does the actual JSON-RPC communication happen in the runtime?

While the specific JSON-RPC client implementation may reside in related assemblies, AssemblyInfo.cs in the Runtime folder defines the assembly boundaries and entry points that receive marshaled parameters from the Python server. The runtime assembly acts as the host environment that processes these forwarded calls and routes them to the appropriate tool handlers, making it the central coordination point for MCP communication.

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