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

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

• 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 located at 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 (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

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

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

#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

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
• UI Access: Use Edit ▶ Preferences ▶ Unity MCP to modify settings via 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.

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) 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 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.

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