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

Unity MCP reads a JSON configuration file at 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:

{
  "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:

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) — The root configuration object containing the mcpServers dictionary.
2. McpConfigServers (MCPForUnity/Editor/Models/MCPConfigServers.cs) — Container class holding the unityMCP server entry.
3. McpConfigServer (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 and concrete implementations like 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

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

// 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

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) — Manages persistent WebSocket connections using the reconnectAttempts and reconnectDelayMs settings.
• StdioTransportClient (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 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 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 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.

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