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

> Discover the core Unity MCP runtime bridge. This essential C# assembly facilitates communication between Unity and Python MCP servers via JSON-RPC, version shims, and type serialization.

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

---

**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`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/UnityCompatShims.cs): A documentation marker cataloging all compatibility shims
- [`UnityFindObjectsCompat.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/UnityFindObjectsCompat.cs): Handles `Object.FindObjectsByType` versus the older `Object.FindObjectsOfType` API differences
- [`UnityPhysicsCompat.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/UnityPhysicsCompat.cs): Abstracts physics API changes such as `Physics.RaycastAll` variations
- [`UnityObjectIdCompat.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/UnityObjectIdCompat.cs): Manages object-ID handling inconsistencies across Unity releases
- [`UnityAssembliesCompat.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/AssemblyInfo.cs)**: Defines assembly attributes, version metadata, and GUIDs required by Unity's compilation pipeline
- **[`UnityCompatShims.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/UnityCompatShims.cs)**: Documents the shim architecture and explains when new compatibility layers are necessary
- **[`UnityTypeConverters.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/UnityTypeConverters.cs)**: Implements JSON serialization for Unity mathematics structs and color types
- **[`ScreenshotUtility.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/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:

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

```

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

```

```csharp
// 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`](https://github.com/CoplayDev/unity-mcp/blob/main/AssemblyInfo.cs) and related handlers
- Version compatibility shims in files like [`UnityFindObjectsCompat.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/UnityFindObjectsCompat.cs) and [`UnityPhysicsCompat.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/UnityPhysicsCompat.cs) ensure the plugin works across Unity 2021 through 2026
- [`UnityTypeConverters.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/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.