# What Is the McpServer Component in Unity C#? A Complete Technical Guide

> Discover the McpServer component in Unity C#. Learn how this TCP runtime bridge facilitates Editor and MCP client communication for command dispatch and resource fetching.

- Repository: [いすず/unitymcp](https://github.com/isuzu-shiranui/unitymcp)
- Tags: deep-dive
- Published: 2026-03-04

---

**The McpServer component is a TCP-based runtime bridge that enables bidirectional communication between the Unity Editor and external MCP (Model Context Protocol) clients, handling command dispatch, resource fetching, and thread-safe Unity API execution.**

The `McpServer` class, located in the `UnityMCP.Editor.Core` namespace within the [isuzu-shiranui/unitymcp](https://github.com/isuzu-shiranui/unitymcp) repository, serves as the central nervous system for the Unity MCP package. It manages the connection lifecycle, routes incoming JSON commands to registered handlers, and ensures all Unity API interactions occur on the main thread.

## Core Responsibilities of the McpServer Component

The McpServer component fulfills four primary architectural responsibilities to maintain stable communication between the Unity Editor and TypeScript-based MCP servers.

### Connection Management (TCP/UDP)

The server maintains a persistent TCP connection using a `TcpClient` instance stored in the `client` field. It spawns a background thread (`clientThread`) that executes the `RunClient` method to handle incoming network traffic. For automatic server discovery, the component optionally listens for UDP broadcasts on a configurable `broadcastPort`.

Reconnection logic implements exponential back-off through the `reconnectDelay` and `maxReconnectDelay` fields. When a connection drops, the `TryConnect` method (lines 334-398 in [`McpServer.cs`](https://github.com/isuzu-shiranui/unitymcp/blob/main/McpServer.cs)) waits progressively longer intervals before attempting to reconnect, preventing aggressive polling that could overwhelm the network stack.

### Command Handling and Dispatch

Incoming commands follow a "prefix.action" naming convention (e.g., `scene.createObject`). The server stores command handlers in a `Dictionary<string, HandlerRegistration>` called `commandHandlers`. When the `ExecuteCommand` method (lines 800-885) receives a JSON payload, it:

1. Parses the command string to extract the prefix
2. Looks up the corresponding `IMcpCommandHandler` implementation
3. Queues execution on the main thread via `ExecuteOnMainThread`
4. Raises the `CommandExecuted` event upon completion

This architecture allows developers to extend the server with custom functionality by implementing the `IMcpCommandHandler` interface and registering instances via `RegisterHandler`.

### Resource Handling

Resource handlers provide read-only access to Unity project data, such as asset lists or scene hierarchies. The `resourceHandlers` dictionary stores implementations of `IMcpResourceHandler`. The `ProcessResourceRequest` method (lines 668-748) handles resource queries by:

- Validating the requested resource name exists in the dictionary
- Queuing the fetch operation on the main thread
- Waiting up to 5 seconds for the handler to return data
- Serializing the result as a JSON response

This pattern ensures that resource-intensive queries (like scanning the entire `AssetDatabase`) never block the network thread.

### Thread-Safe Unity Main Thread Execution

Unity's API is not thread-safe; all calls must originate from the main thread. The McpServer solves this through a lock-protected `Queue<Action>` named `mainThreadQueue`. Background threads enqueue actions using `ExecuteOnMainThread` (lines 889-896), while `EditorApplication.update` periodically invokes `ProcessMainThreadQueue` (lines 664-682) to drain the queue on the main thread.

This producer-consumer pattern allows the TCP client thread to remain responsive while ensuring Unity API calls (like instantiating GameObjects or modifying scenes) execute safely.

## McpServer Lifecycle and Event Model

Understanding the initialization sequence and event system is crucial for debugging connection issues and implementing reactive UI components.

### Initialization and Construction

The constructor (lines 94-112 in [`McpServer.cs`](https://github.com/isuzu-shiranui/unitymcp/blob/main/McpServer.cs)) initializes the server configuration by reading `McpSettings.instance`, which provides the host address, TCP port, and UDP discovery settings. It also registers the `ProcessMainThreadQueue` method with `EditorApplication.update` to enable the main thread action processing loop.

```csharp
public McpServer(int port = 0)
{
    // Loads settings from McpSettings.asset
    this.port = port > 0 ? port : McpSettings.instance.port;
    // Registers main thread queue processing
    EditorApplication.update += ProcessMainThreadQueue;
}

```

### Starting the Server

The `Start` method (lines 146-173) creates a `CancellationTokenSource` to coordinate graceful shutdown, spawns the `clientThread` that runs `RunClient`, and optionally starts the UDP broadcast listener if discovery is enabled in settings.

### Connection Events

The McpServer exposes four key events that implement the standard .NET `EventHandler` pattern:

- **`Connected`**: Raised in `OnConnected` (line 480) immediately after `TryConnect` successfully establishes the TCP socket.
- **`Disconnected`**: Raised in `OnDisconnected` (lines 571-579) when the connection drops, the cancellation token triggers, or an unrecoverable network error occurs.
- **`CommandExecuted`**: Raised in `OnCommandExecuted` (lines 848-850) after `ExecuteCommand` completes, providing the prefix, action, and result payload.
- **`ResourceFetched`**: Raised in `OnResourceFetched` (lines 448-452) when `FetchResourceData` successfully retrieves resource data.

These events enable decoupled architectures where UI components or logging systems can react to server state changes without modifying the core server code.

### Shutdown and Disposal

The `Stop` method (lines 184-206) initiates graceful shutdown by canceling the token, closing sockets, and joining the client thread. `Dispose` (lines 271-280) ensures cleanup of unmanaged resources and removes the `EditorApplication.update` callback to prevent memory leaks in the editor.

## Implementing Custom Handlers

Extending the McpServer requires implementing the handler interfaces and registering instances before calling `Start`.

### Command Handlers (IMcpCommandHandler)

Command handlers process actions that modify the Unity state or execute editor operations. The interface requires:

```csharp
public interface IMcpCommandHandler
{
    string CommandPrefix { get; }
    string Description { get; }
    JObject Execute(string action, JObject parameters);
}

```

The `Execute` method receives the action suffix (the part after the prefix) and a JSON parameter object. It must return a JSON object containing at least a `status` field.

### Resource Handlers (IMcpResourceHandler)

Resource handlers provide read-only data access. The interface contract is:

```csharp
public interface IMcpResourceHandler
{
    string ResourceName { get; }
    string ResourceUri { get; }
    string Description { get; }
    JObject FetchResource(JObject parameters);
}

```

Registration occurs via `RegisterResourceHandler`, which stores the instance in the `resourceHandlers` dictionary keyed by `ResourceName`.

### Practical Example: Asset List Resource

Here is a complete resource handler implementation that exposes the project's prefab assets:

```csharp
using UnityEditor;
using UnityMCP.Editor.Core;
using Newtonsoft.Json.Linq;
using System.Linq;

public class AssetListResource : IMcpResourceHandler
{
    public string ResourceName => "assetList";
    public string ResourceUri => null;
    public string Description => "Provides a list of all prefab assets in the project";

    public JObject FetchResource(JObject parameters)
    {
        var guids = AssetDatabase.FindAssets("t:Prefab");
        var paths = guids.Select(guid => AssetDatabase.GUIDToAssetPath(guid)).ToArray();

        return new JObject
        {
            ["status"] = "success",
            ["count"] = paths.Length,
            ["assets"] = new JArray(paths)
        };
    }
}

```

Register this during server initialization:

```csharp
server.RegisterResourceHandler(new AssetListResource());

```

When the TypeScript MCP client sends `{"type":"resource","command":"assetList.get","id":"42"}`, the server will execute `FetchResource` on the main thread and return the JSON array of prefab paths.

## Key Source Files and Architecture

The McpServer component is distributed across several files in the `jp.shiranui-isuzu.unity-mcp` package:

| File | Role |
|------|------|
| [`Editor/Core/McpServer.cs`](https://github.com/isuzu-shiranui/unitymcp/blob/main/Editor/Core/McpServer.cs) | Central server implementation containing TCP client management, the `RunClient` loop, `ExecuteCommand`, `ProcessResourceRequest`, and the main thread queue processing. |
| [`Editor/Core/McpServiceManager.cs`](https://github.com/isuzu-shiranui/unitymcp/blob/main/Editor/Core/McpServiceManager.cs) | High-level façade that manages a singleton `McpServer` instance for the editor session, handling automatic startup and shutdown. |
| [`Editor/Settings/McpSettings.cs`](https://github.com/isuzu-shiranui/unitymcp/blob/main/Editor/Settings/McpSettings.cs) | ScriptableObject storing host, port, UDP discovery settings, and per-handler enable states, editable via the Unity Settings window. |
| [`Editor/Core/IMcpCommandHandler.cs`](https://github.com/isuzu-shiranui/unitymcp/blob/main/Editor/Core/IMcpCommandHandler.cs) | Interface defining the contract for command handlers (`CommandPrefix`, `Execute`). |
| [`Editor/Core/IMcpResourceHandler.cs`](https://github.com/isuzu-shiranui/unitymcp/blob/main/Editor/Core/IMcpResourceHandler.cs) | Interface defining the contract for resource handlers (`ResourceName`, `FetchResource`). |
| `Samples~/UnityMCPHandlerSamples/Editor/` | Example implementations demonstrating custom handler registration and usage patterns. |

These files collectively implement the Model Context Protocol server-side runtime, enabling external AI assistants and tools to interact with the Unity Editor through a structured JSON-RPC-like interface over TCP.

## Summary

- **The McpServer component** (`UnityMCP.Editor.Core.McpServer`) acts as the TCP bridge between the Unity Editor and external MCP clients, managing connection state, command routing, and resource access.
- **Connection management** uses a background thread with exponential back-off reconnection logic, optional UDP discovery, and graceful cancellation token-based shutdown.
- **Command and resource handlers** follow an interface-based plugin architecture (`IMcpCommandHandler`, `IMcpResourceHandler`) allowing developers to extend functionality by registering custom implementations.
- **Thread safety** is enforced through a lock-protected main thread action queue (`mainThreadQueue`), ensuring all Unity API calls execute on the editor's main thread while network operations remain asynchronous.
- **Event-driven architecture** exposes `Connected`, `Disconnected`, `CommandExecuted`, and `ResourceFetched` events for reactive UI updates and logging without coupling to the server internals.

## Frequently Asked Questions

### What is the primary purpose of the McpServer component in Unity C#?

The McpServer component serves as the runtime host that enables the Unity Editor to communicate with external Model Context Protocol (MCP) clients over TCP. It handles incoming JSON commands, routes them to registered handlers, manages resource requests, and ensures all Unity API interactions occur safely on the main thread, effectively turning the Editor into an MCP-compatible server.

### How does McpServer handle thread safety with Unity APIs?

The component implements a producer-consumer pattern using a `Queue<Action>` named `mainThreadQueue` protected by a lock object. Background network threads enqueue actions via `ExecuteOnMainThread`, while `EditorApplication.update` periodically calls `ProcessMainThreadQueue` to execute these actions on Unity's main thread. This design prevents cross-thread access violations while maintaining responsive network I/O.

### What is the difference between command handlers and resource handlers in McpServer?

Command handlers implement `IMcpCommandHandler` and process actions that may modify Unity state, such as creating GameObjects or modifying scenes; they follow a "prefix.action" naming convention and return JSON results via the `Execute` method. Resource handlers implement `IMcpResourceHandler` and provide read-only access to project data like asset lists or scene hierarchies through the `FetchResource` method, with built-in timeout handling up to 5 seconds.

### How do I configure the McpServer connection settings in Unity?

Configuration is managed through the `McpSettings` ScriptableObject located at [`Editor/Settings/McpSettings.cs`](https://github.com/isuzu-shiranui/unitymcp/blob/main/Editor/Settings/McpSettings.cs). You can edit these settings via Unity's Preferences window to adjust the TCP host, port number, enable UDP discovery for automatic server detection, and toggle individual handler registrations. The `McpServer` constructor automatically reads these settings during initialization, or you can pass a custom port parameter to the constructor for programmatic configuration.