# How to Configure Advanced Settings for Unity MCP Behavior: Complete Guide

> Configure advanced Unity MCP behavior settings. Learn to control host, port, auto-start, and handlers programmatically or via Preferences using McpSettings.

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

---

**Unity MCP stores all configuration in the `McpSettings` ScriptableSingleton, which you can modify through the Preferences window or programmatically via `McpSettings.instance` to control host, port, auto-start behavior, and individual handler enable-states.**

Unity MCP (Message-Command-Protocol) provides a flexible architecture for editor automation, but fine-tuning its behavior requires understanding how to configure advanced settings for Unity MCP behavior. Whether you need to change network endpoints, disable specific command handlers, or automate configuration for CI builds, the `McpSettings` class in [`jp.shiranui-isuzu.unity-mcp/Editor/Settings/McpSettings.cs`](https://github.com/isuzu-shiranui/unitymcp/blob/main/jp.shiranui-isuzu.unity-mcp/Editor/Settings/McpSettings.cs) serves as the central configuration hub.

## Where Unity MCP Settings Are Stored

The `McpSettings` class is a `ScriptableSingleton` that persists data to `UserSettings/UnityMcpSettings.asset` in your Unity Preferences folder. This singleton exposes all configurable values as serializable properties and provides a `Save()` method to persist runtime changes.

Key implementation details from [`McpSettings.cs`](https://github.com/isuzu-shiranui/unitymcp/blob/main/McpSettings.cs):

- **Singleton Access**: Use `McpSettings.instance` to read or modify settings
- **Persistence**: Call `McpSettings.instance.Save()` to write changes to disk
- **Handler States**: Two dictionaries track enable states: `handlerEnabledStates` (for commands) and `resourceHandlerEnabledStates` (for resources)

## Accessing the Unity MCP Preferences UI

For manual configuration, Unity MCP registers a custom preferences panel via [`McpSettingsProvider.cs`](https://github.com/isuzu-shiranui/unitymcp/blob/main/McpSettingsProvider.cs) located at [`jp.shiranui-isuzu.unity-mcp/Editor/Settings/McpSettingsProvider.cs`](https://github.com/isuzu-shiranui/unitymcp/blob/main/jp.shiranui-isuzu.unity-mcp/Editor/Settings/McpSettingsProvider.cs). Access this through **Edit ▶ Preferences ▶ Unity MCP**.

The provider implements:

- **Connection Settings**: Host, port, and UDP discovery toggles
- **Behavior Toggles**: Auto-start on launch, auto-restart on play mode changes, detailed logging
- **Handler Management**: Fold-out sections for Command Handlers and Resource Handlers with individual enable/disable toggles

When you modify values in this window, `McpSettingsProvider` updates the singleton instance and automatically calls `Save()` when the preferences window closes.

## Core Configuration Options

The following table details the advanced settings available in `McpSettings`:

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `host` | string | `127.0.0.1` | IP address the MCP client connects to |
| `port` | int | `27182` | TCP port for the TypeScript server |
| `autoStartOnLaunch` | bool | `true` | Automatically start MCP when Unity opens |
| `autoRestartOnPlayModeChange` | bool | `true` | Restart client when entering/exiting Play mode |
| `detailedLogs` | bool | `true` | Enable verbose `Debug.Log` output |
| `useUdpDiscovery` | bool | `true` | Enable broadcast-based server discovery |
| `udpDiscoveryPort` | int | `27183` | UDP port for discovery broadcasts |

## Configuring Command and Resource Handlers

Unity MCP uses a handler registration system defined in [`McpServer.cs`](https://github.com/isuzu-shiranui/unitymcp/blob/main/McpServer.cs) ([`jp.shiranui-isuzu.unity-mcp/Editor/Core/McpServer.cs`](https://github.com/isuzu-shiranui/unitymcp/blob/main/jp.shiranui-isuzu.unity-mcp/Editor/Core/McpServer.cs)). Each command prefix and resource type can be individually enabled or disabled.

### Handler Enable-States

- **`handlerEnabledStates`**: Dictionary mapping command prefixes (e.g., `"unity"`) to boolean values
- **`resourceHandlerEnabledStates`**: Dictionary mapping resource types to boolean values

The `McpServer` reads these dictionaries during handler registration (methods `RegisterHandler` around lines 1010-1016 and `RegisterResourceHandler` around lines 1050-1060) and when processing commands (`ExecuteCommand` lines 820-860) and resources (`FetchResourceData` lines 910-950).

### Programmatically Updating Handler States

```csharp
using UnityMCP.Editor.Settings;

// Disable the "unity" command prefix
McpSettings.instance.UpdateHandlerEnabledState("unity", false);

// Disable the "asset" resource handler
McpSettings.instance.UpdateResourceHandlerEnabledState("asset", false);

// Persist changes
McpSettings.instance.Save();

```

## Runtime vs Persistent Configuration Changes

Understanding when changes take effect is crucial for configuring advanced settings for Unity MCP behavior:

**Runtime Changes (Immediate)**
- Modifying `McpSettings.instance` properties updates the in-memory singleton immediately
- Handler enable-state changes take effect instantly for subsequent commands
- Connection settings (host/port) require a client restart to apply

**Persistent Changes (Survive Restart)**
- Call `McpSettings.instance.Save()` to write to `UserSettings/UnityMcpSettings.asset`
- Preferences window automatically saves when closed
- Persistent settings are loaded when `McpServer` initializes on next Unity launch

## Practical Code Examples

### Disabling a Command Handler from a Build Script

```csharp
using UnityMCP.Editor.Settings;
using UnityEditor;

[InitializeOnLoadMethod]
static void ConfigureMCPForProduction()
{
    // Disable potentially dangerous console commands in production builds
    McpSettings.instance.UpdateHandlerEnabledState("console", false);
    McpSettings.instance.Save();
    
    Debug.Log("Unity MCP: Disabled console handler for production environment");
}

```

### Switching to a Custom Host and Port for CI

```csharp
#if UNITY_EDITOR
using UnityMCP.Editor.Settings;
using UnityEditor;

[InitializeOnLoadMethod]
static void ConfigureMCPForCI()
{
    var settings = McpSettings.instance;
    
    // Connect to CI server instead of localhost
    settings.host = "10.0.0.5";
    settings.port = 4000;
    
    // Prevent auto-start to allow manual control in CI
    settings.autoStartOnLaunch = false;
    settings.autoRestartOnPlayModeChange = false;
    
    settings.Save();
    Debug.Log($"Unity MCP configured for CI: {settings.host}:{settings.port}");
}
#endif

```

### Enabling UDP Discovery Only for Debug Builds

```csharp
using UnityMCP.Editor.Settings;

#if DEBUG
    McpSettings.instance.useUdpDiscovery = true;
    McpSettings.instance.detailedLogs = true;
#else
    McpSettings.instance.useUdpDiscovery = false;
    McpSettings.instance.detailedLogs = false;
#endif

McpSettings.instance.Save();

```

## Summary

- **Central Configuration**: All Unity MCP settings live in the `McpSettings` ScriptableSingleton at [`jp.shiranui-isuzu.unity-mcp/Editor/Settings/McpSettings.cs`](https://github.com/isuzu-shiranui/unitymcp/blob/main/jp.shiranui-isuzu.unity-mcp/Editor/Settings/McpSettings.cs)
- **UI Access**: Use **Edit ▶ Preferences ▶ Unity MCP** to modify settings via [`McpSettingsProvider.cs`](https://github.com/isuzu-shiranui/unitymcp/blob/main/McpSettingsProvider.cs)
- **Programmatic Control**: Access `McpSettings.instance` to change host, port, auto-start behavior, and logging levels at runtime
- **Handler Granularity**: Enable or disable individual command and resource handlers using `UpdateHandlerEnabledState()` and `UpdateResourceHandlerEnabledState()`
- **Persistence**: Call `Save()` on the settings instance to persist changes to `UserSettings/UnityMcpSettings.asset`

## Frequently Asked Questions

### How do I change the Unity MCP server host and port programmatically?

Access the `McpSettings.instance` singleton and set the `host` and `port` properties before the client starts. For example: `McpSettings.instance.host = "192.168.1.100"; McpSettings.instance.port = 3000; McpSettings.instance.Save();`. These values are read by `McpServer` during initialization in [`jp.shiranui-isuzu.unity-mcp/Editor/Core/McpServer.cs`](https://github.com/isuzu-shiranui/unitymcp/blob/main/jp.shiranui-isuzu.unity-mcp/Editor/Core/McpServer.cs).

### Can I disable specific Unity MCP command handlers without removing the code?

Yes. Use the `UpdateHandlerEnabledState` method on `McpSettings.instance` to toggle individual handlers by their command prefix. For example, `McpSettings.instance.UpdateHandlerEnabledState("unity", false);` disables all commands under the "unity" prefix. The `McpServer` checks these states in `ExecuteCommand` (around line 820) before invoking handlers.

### Why are my Unity MCP settings not persisting between Unity sessions?

You must call `Save()` on the `McpSettings` instance after making changes. The singleton lives in memory during the editor session, but changes are only written to `UserSettings/UnityMcpSettings.asset` when `Save()` is invoked. The Preferences window ([`McpSettingsProvider.cs`](https://github.com/isuzu-shiranui/unitymcp/blob/main/McpSettingsProvider.cs)) handles this automatically when closed, but programmatic changes require manual `Save()` calls.

### How do I prevent Unity MCP from auto-starting when Unity launches?

Set `McpSettings.instance.autoStartOnLaunch = false;` and call `Save()`. This boolean is checked by [`McpEditorInitializer.cs`](https://github.com/isuzu-shiranui/unitymcp/blob/main/McpEditorInitializer.cs) during the editor load sequence. When disabled, the `McpServer` will not initialize automatically, allowing you to start it manually via the Preferences window or your own editor scripts.