Unity MCP Configuration Options in Unity Preferences: Complete Settings Guide

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, which renders the editable fields defined in the McpSettings ScriptableSingleton class located at Editor/Settings/McpSettings.cs.

Server Connection Settings

Host

The Host field maps to McpSettings.host (lines 22-24 in 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 (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 (lines 126-139).

Programmatic Configuration

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

Accessing and Modifying Settings

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

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

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.
• The Preferences UI (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.

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