# Unity MCP Configuration Options in Unity Preferences: Complete Settings Guide

> Master Unity MCP configuration options in Unity Preferences. Learn to set server host port, UDP discovery, auto start, logging, and command handlers for seamless integration.

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

---

**Unity MCP configuration options are managed through the Unity Preferences window under Edit > Preferences > Unity MCP, where you can set server host/port, UDP discovery settings, auto-start behaviors, logging levels, and toggle individual command handlers via the McpSettings ScriptableSingleton.**

The Unity MCP package (`isuzu-shiranui/unitymcp`) exposes all runtime configuration through a centralized preferences panel. These Unity MCP configuration options control how the Model Context Protocol server binds to network interfaces, discovers clients, manages its lifecycle, and handles individual commands without requiring code changes.

## Accessing Unity MCP Preferences

Navigate to **Edit > Preferences > Unity MCP** in the Unity Editor. The UI is implemented in [`Editor/Settings/McpSettingsProvider.cs`](https://github.com/isuzu-shiranui/unitymcp/blob/main/Editor/Settings/McpSettingsProvider.cs), which renders the editable fields defined in the `McpSettings` ScriptableSingleton class located at [`Editor/Settings/McpSettings.cs`](https://github.com/isuzu-shiranui/unitymcp/blob/main/Editor/Settings/McpSettings.cs).

## Server Connection Settings

### Host

The **Host** field maps to `McpSettings.host` (lines 22-24 in [`McpSettings.cs`](https://github.com/isuzu-shiranui/unitymcp/blob/main/McpSettings.cs)). This sets the IP address or hostname the MCP server binds to. Default: `127.0.0.1`.

### Port

The **Port** field maps to `McpSettings.port` (lines 28-30). This defines the TCP port the server listens on. Default: `27182`.

## UDP Discovery Configuration

### Use UDP Discovery

The **Use UDP Discovery** toggle corresponds to `McpSettings.useUdpDiscovery` (lines 50-53). When enabled, the server broadcasts its presence via UDP for automatic client discovery.

### UDP Discovery Port

The **UDP Discovery Port** field maps to `McpSettings.udpDiscoveryPort` (lines 56-60). Default: `27183`.

## Automatic Server Lifecycle

### Auto-start on Launch

The **Auto-start on Launch** toggle maps to `McpSettings.autoStartOnLaunch` (lines 34-36). Automatically initializes the MCP server when Unity starts.

### Auto-restart on Play-mode Change

The **Auto-restart on Play-mode Change** toggle corresponds to `McpSettings.autoRestartOnPlayModeChange` (lines 38-41). Restarts the server each time you enter or exit Play mode.

## Logging and Debugging

The **Detailed Logs** toggle maps to `McpSettings.detailedLogs` (lines 44-48). Enables verbose output in the MCP console for debugging connection issues.

## Handler Toggles

### Command Handlers

The **Command Handlers** fold-out list controls `McpSettings.handlerEnabledStates` (lines 64-66). This dictionary stores per-handler boolean values allowing you to enable or disable specific MCP commands. The UI implementation renders these in [`McpSettingsProvider.cs`](https://github.com/isuzu-shiranui/unitymcp/blob/main/McpSettingsProvider.cs) (lines 71-84).

### Resource Handlers

The **Resource Handlers** fold-out list maps to `McpSettings.resourceHandlerEnabledStates` (lines 68-71). Uses the same dictionary pattern for resource handlers, with UI code in [`McpSettingsProvider.cs`](https://github.com/isuzu-shiranui/unitymcp/blob/main/McpSettingsProvider.cs) (lines 126-139).

## Programmatic Configuration

You can modify these settings via script using the `McpSettings` singleton.

### Accessing and Modifying Settings

```csharp
using UnityMCP.Editor.Settings;

public static class McpConfigUtility
{
    public static void SetCustomHost(string host, int port)
    {
        var cfg = McpSettings.instance;
        cfg.host = host;
        cfg.port = port;
        cfg.Save(); // persist changes (same as Preferences UI)
    }

    public static void EnableDetailedLogs(bool enable)
    {
        var cfg = McpSettings.instance;
        cfg.detailedLogs = enable;
        cfg.Save();
    }
}

```

### Toggling Command Handlers Programmatically

```csharp
using UnityMCP.Editor.Settings;

public static class HandlerToggle
{
    public static void SetHandlerEnabled(string commandPrefix, bool enabled)
    {
        // Updates the dictionary and writes the asset to disk
        McpSettings.instance.UpdateHandlerEnabledState(commandPrefix, enabled);
    }
}

```

### Opening Preferences via Script

```csharp
using UnityEditor;

[MenuItem("Tools/Unity MCP/Preferences")]
static void OpenMcpPreferences()
{
    SettingsService.OpenUserPreferences("Preferences/Unity MCP");
}

```

## Summary

- Unity MCP configuration options are centralized in the `McpSettings` ScriptableSingleton at [`Editor/Settings/McpSettings.cs`](https://github.com/isuzu-shiranui/unitymcp/blob/main/Editor/Settings/McpSettings.cs).
- The Preferences UI ([`McpSettingsProvider.cs`](https://github.com/isuzu-shiranui/unitymcp/blob/main/McpSettingsProvider.cs)) exposes server address, UDP discovery, lifecycle automation, logging, and handler toggles.
- Default server binds to `127.0.0.1:27182` with optional UDP discovery on port `27183`.
- All settings can be modified programmatically via `McpSettings.instance` and persisted with `Save()`.

## Frequently Asked Questions

### Where are Unity MCP settings stored on disk?

The settings are stored as a ScriptableObject asset at `UserSettings/UnityMcpSettings.asset` within your Unity project. This path is defined by the `[FilePath]` attribute on the `McpSettings` class.

### Can I change the host to allow remote connections?

Yes. By default, `host` is set to `127.0.0.1` (localhost). You can change this to `0.0.0.0` or a specific network interface IP in the Preferences window or via `McpSettings.instance.host` to allow remote MCP clients to connect.

### What happens when Auto-restart on Play-mode Change is enabled?

When enabled, the MCP server automatically shuts down and restarts each time you enter or exit Play mode in the Unity Editor. This ensures a clean state between edit-time and play-time sessions, preventing port conflicts or stale connections.

### How do I disable specific MCP commands without modifying code?

Use the **Command Handlers** fold-out list in the Unity MCP Preferences panel. Each registered command handler appears as a toggle. Unchecking a handler updates the `handlerEnabledStates` dictionary in `McpSettings`, preventing that specific command from being processed by the server.