# Unity MCP Configuration Options: Complete Guide to JSON Settings and C# Models

> Explore Unity MCP configuration options in this complete guide. Learn to manage JSON settings and C# models for seamless server connection and reconnection behavior.

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

---

**Unity MCP reads a JSON configuration file at [`Assets/Plugins/MCPForUnity/mcp_config.json`](https://github.com/CoplayDev/unity-mcp/blob/main/Assets/Plugins/MCPForUnity/mcp_config.json) containing server connection details under the `mcpServers.unityMCP` object, with fields for URL, authentication, transport type, and reconnection behavior.**

The Unity MCP bridge from the CoplayDev/unity-mcp repository enables AI assistants to communicate with the Unity Editor through a configurable middleware layer. Understanding the available Unity MCP configuration options allows you to customize server endpoints, enable authentication, switch between transport protocols, and manage connection resiliency for your specific development environment.

## Configuration File Location and Structure

Unity MCP expects a JSON configuration file that the Editor reads at startup. The package uses `Newtonsoft.Json` to deserialize this file into strongly typed C# models defined in the `MCPForUnity/Editor/Models/` directory.

### Default File Path

By default, the system searches for the configuration at:

```

Assets/Plugins/MCPForUnity/mcp_config.json

```

If this file is missing, the Unity MCP client falls back to a built-in default that points to a local server on `127.0.0.1:5000`.

### JSON Schema Overview

The root object must contain an **`mcpServers`** property. Inside this object, the key **`unityMCP`** holds the specific server configuration that Unity will connect to:

```json
{
  "mcpServers": {
    "unityMCP": {
      "url": "http://127.0.0.1:5000",
      "useWebSocket": true
    }
  }
}

```

## Server Configuration Options

The `unityMCP` object supports the following fields, defined in the `McpConfigServer` class within [`MCPForUnity/Editor/Models/MCPConfigServer.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/MCPForUnity/Editor/Models/MCPConfigServer.cs):

| Field | Type | Description | Default |
|-------|------|-------------|---------|
| **`url`** | string | Base HTTP or WebSocket URL of the MCP server where Unity sends commands and receives events. | `"http://127.0.0.1:5000"` |
| **`authToken`** | string | Optional bearer token for server authentication. When omitted, the server runs in unauthenticated mode. | `null` |
| **`useWebSocket`** | boolean | When `true`, opens a persistent WebSocket connection; `false` falls back to legacy stdio transport. | `true` |
| **`clientId`** | string | User-defined identifier attached to every request; useful when multiple AI assistants share one server instance. | `"default"` |
| **`transport`** | string | Explicit transport selection: `"websocket"` or `"stdio"`. Overrides the `useWebSocket` field. | Derived from `useWebSocket` |
| **`reconnectAttempts`** | integer | Number of automatic reconnection attempts if the transport drops. | `5` |
| **`reconnectDelayMs`** | integer | Milliseconds to wait between reconnection attempts. | `2000` |
| **`logLevel`** | string | Verbosity of client-side logging: `"debug"`, `"info"`, `"warning"`, or `"error"`. | `"info"` |

## Configuration Classes in the Source Code

The Unity MCP codebase implements a three-tier model hierarchy to represent these settings:

1. **`McpConfig`** ([`MCPForUnity/Editor/Models/McpConfig.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/MCPForUnity/Editor/Models/McpConfig.cs)) — The root configuration object containing the `mcpServers` dictionary.
2. **`McpConfigServers`** ([`MCPForUnity/Editor/Models/MCPConfigServers.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/MCPForUnity/Editor/Models/MCPConfigServers.cs)) — Container class holding the `unityMCP` server entry.
3. **`McpConfigServer`** ([`MCPForUnity/Editor/Models/MCPConfigServer.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/MCPForUnity/Editor/Models/MCPConfigServer.cs)) — Concrete class defining individual server properties including `url`, `authToken`, and transport booleans.

The deserialization and initialization logic resides in [`McpClientConfiguratorBase.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/McpClientConfiguratorBase.cs) and concrete implementations like [`VSCodeConfigurator.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/VSCodeConfigurator.cs), which expose these values to the transport layer.

## Loading and Applying Configuration

You can programmatically load and modify configurations using the `McpConfig` model and transport clients.

### Loading a Custom Configuration File

```csharp
using System.IO;
using Newtonsoft.Json;
using MCPForUnity.Editor.Models;
using MCPForUnity.Editor.Services.Transport;
using UnityEngine;

// Load from the standard Plugins location
string configPath = Path.Combine(Application.dataPath, 
                                 "Plugins/MCPForUnity/mcp_config.json");
string json = File.ReadAllText(configPath);
McpConfig cfg = JsonConvert.DeserializeObject<McpConfig>(json);

// Initialize transport based on configuration
IMcpTransportClient client = cfg.mcpServers.unityMCP.useWebSocket
    ? new WebSocketTransportClient(cfg.mcpServers.unityMCP)
    : new StdioTransportClient(cfg.mcpServers.unityMCP);

await client.ConnectAsync();

```

### Runtime URL Override

```csharp
// Load defaults and override for testing
McpConfig cfg = McpConfigLoader.LoadDefault();
cfg.mcpServers.unityMCP.url = "http://localhost:6000";

TransportManager.Instance.SetClient(
    new WebSocketTransportClient(cfg.mcpServers.unityMCP));

```

### Using Environment-Based Authentication

```csharp
McpConfig cfg = McpConfigLoader.LoadDefault();
cfg.mcpServers.unityMCP.authToken = Environment.GetEnvironmentVariable("MCP_API_KEY");

TransportManager.Instance.SetClient(
    new WebSocketTransportClient(cfg.mcpServers.unityMCP));

```

## Transport-Specific Implementation

The `useWebSocket` and `transport` fields determine which concrete class handles communication:

- **`WebSocketTransportClient`** ([`MCPForUnity/Editor/Services/Transport/WebSocketTransportClient.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/MCPForUnity/Editor/Services/Transport/WebSocketTransportClient.cs)) — Manages persistent WebSocket connections using the `reconnectAttempts` and `reconnectDelayMs` settings.
- **`StdioTransportClient`** ([`MCPForUnity/Editor/Services/Transport/StdioTransportClient.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/MCPForUnity/Editor/Services/Transport/StdioTransportClient.cs)) — Implements standard input/output transport for legacy compatibility.

When the `transport` field is explicitly set to `"websocket"` or `"stdio"`, it takes precedence over the boolean `useWebSocket` flag.

## Summary

- Unity MCP configuration resides in [`Assets/Plugins/MCPForUnity/mcp_config.json`](https://github.com/CoplayDev/unity-mcp/blob/main/Assets/Plugins/MCPForUnity/mcp_config.json) and follows a nested JSON structure with `mcpServers.unityMCP` as the primary configuration object.
- **Key configurable fields** include `url` (server endpoint), `authToken` (security), `useWebSocket` (transport protocol), `clientId` (multi-tenant identification), and reconnection parameters (`reconnectAttempts`, `reconnectDelayMs`).
- The C# models `McpConfig`, `McpConfigServers`, and `McpConfigServer` in the `MCPForUnity/Editor/Models/` directory define the strongly typed schema used by the client configurators.

- Configuration values flow from JSON deserialization through `McpClientConfiguratorBase` implementations to concrete transport clients like `WebSocketTransportClient`.

## Frequently Asked Questions

### How do I secure my Unity MCP connection with authentication?

Add an `authToken` field to your JSON configuration. The `WebSocketTransportClient` reads this value from the `McpConfigServer` instance and includes it as a bearer token in connection headers. If the token is omitted, the server operates in unauthenticated mode.

### Can I run multiple Unity instances against the same MCP server?

Yes. Assign a unique `clientId` to each Unity project in its respective [`mcp_config.json`](https://github.com/CoplayDev/unity-mcp/blob/main/mcp_config.json) file. This identifier attaches to every request, allowing the server to distinguish between different Editor instances or AI assistants sharing the same endpoint.

### What happens if the configuration file is missing?

If [`Assets/Plugins/MCPForUnity/mcp_config.json`](https://github.com/CoplayDev/unity-mcp/blob/main/Assets/Plugins/MCPForUnity/mcp_config.json) is not found, the Unity MCP package uses a hardcoded fallback that points to `http://127.0.0.1:5000` with WebSocket transport enabled. You can verify this behavior in the `McpConfigLoader` class implementation.

### How do I switch from WebSocket to stdio transport?

Set `"useWebSocket": false` in your configuration, or explicitly specify `"transport": "stdio"`. The `McpClientConfiguratorBase` will instantiate `StdioTransportClient` instead of `WebSocketTransportClient`, bypassing the WebSocket reconnection logic entirely.