Configuration

Relevant source files

The following files were used as context for generating this wiki page:

• Packages/src/Editor/UI/McpEditorWindow.cs
• Packages/src/Editor/Config/CodexTomlConfigService.cs
• Packages/src/Editor/Config/UnityMcpPathResolver.cs
• Packages/src/Editor/Config/McpConstants.cs
• Packages/src/Editor/UI/UIToolkit/Components/EditorConfigSection.cs
• Packages/src/README.md
• Packages/src/ARCHITECTURE.md

The configuration system in uLoopMCP is responsible for managing settings that bridge the Unity Editor with various external LLM-powered development tools like Cursor, Claude Code, and others. It handles the generation and modification of tool-specific configuration files (e.g., mcp.json, config.toml) to establish a connection with the uLoopMCP server. The primary user interface for these settings is the McpEditorWindow, which allows users to select their target tool, manage server settings like port numbers, and adjust security policies.

This system is designed to be extensible, allowing new LLM tools to be supported by adding their specific configuration logic. It centralizes path resolution, settings persistence, and the auto-configuration process, simplifying the user setup experience. Key aspects include managing server connection details, security levels for tool execution, and persisting user preferences across Unity sessions.

Sources: Packages/src/Editor/UI/McpEditorWindow.cs, Packages/src/Editor/Config/UnityMcpPathResolver.cs:12-32, Packages/src/README.md:65-71

Configuration Architecture

The configuration architecture is built around a factory and service pattern to handle different LLM tool configurations in a decoupled manner. The McpEditorWindow acts as the main entry point for the user, delegating configuration tasks to specialized services.

The core components are:

• McpEditorWindow: The main UI window where users interact with settings. It orchestrates calls to configuration services.
• McpConfigServiceFactory: A factory that provides the correct configuration service (IMcpConfigService) based on the selected McpEditorType.
• IMcpConfigService: An interface defining the contract for configuration services, including methods like IsConfigured(), IsUpdateNeeded(int port), and AutoConfigure(int port).
• Concrete IMcpConfigService Implementations: Classes like CodexTomlConfigService that implement the IMcpConfigService interface for a specific tool, handling the parsing and writing of its unique configuration file format (e.g., TOML for Codex).
• UnityMcpPathResolver: A static utility class for resolving all necessary paths, such as configuration file locations and the path to the TypeScript server bundle.

Sources: Packages/src/Editor/UI/McpEditorWindow.cs:21,100,388, Packages/src/Editor/Config/CodexTomlConfigService.cs:8

Component Relationship Diagram

This diagram shows the relationship between the UI, the service factory, and the specific service implementations for handling configuration files.

Auto-Configuration Flow

When a user clicks the "Configure" button in the McpEditorWindow, a sequence of events is triggered to automatically generate or update the configuration file for the selected LLM tool.

This flow ensures that the correct server path and port are written to the appropriate configuration file, enabling the LLM tool to connect to the uLoopMCP server.

Sources: Packages/src/Editor/UI/McpEditorWindow.cs:388-396, Packages/src/Editor/Config/CodexTomlConfigService.cs:95-125

LLM Tool Configuration

uLoopMCP supports various LLM tools, each with its own configuration file location and format. The McpEditorType enum lists all supported tools.

// Source: Packages/src/Editor/Config/UnityMcpPathResolver.cs:9-18
public enum McpEditorType
{
    Cursor,
    ClaudeCode,
    VSCode,
    GeminiCLI,
    Windsurf,
    Codex,
    McpInspector,
}

The system automatically handles the differences between these tools, such as whether the configuration is project-specific or global.

Configuration Files and Locations

The location and name of the configuration file depend on the selected LLM tool. The UnityMcpPathResolver class is responsible for determining the correct path.

Editor Tool	Configuration File	Location
Cursor	mcp.json	{project_root}/.cursor/
ClaudeCode	.mcp.json	{project_root}/
VSCode	mcp.json	{project_root}/.vscode/
GeminiCLI	settings.json	{project_root}/.gemini/
Windsurf	mcp_config.json	~/.codeium/windsurf/
Codex	config.toml	~/.codex/
McpInspector	.inspector.mcp.json	{project_root}/

Note: {project_root} can be the Unity project root or the Git repository root, depending on the "Add Repository Root" setting.

Sources: Packages/src/Editor/Config/UnityMcpPathResolver.cs:124-192

Example Configuration Formats

JSON (mcp.json)

Used by Cursor, VSCode, Claude Code, and others. The configuration specifies the command to run the TypeScript server and passes the Unity TCP port via an environment variable.

{
  "mcpServers": {
    "uLoopMCP": {
      "command": "node",
      "args": [
        "[Unity Package Path]/TypeScriptServer~/dist/server.bundle.js"
      ],
      "env": {
        "UNITY_TCP_PORT": "{port}"
      }
    }
  }
}

Sources: Packages/src/README.md:238-250

TOML (config.toml)

Used by Codex. The CodexTomlConfigService uses regular expressions to find and update the [mcp_servers.uLoopMCP] section within the TOML file.

# Source: Packages/src/Editor/Config/CodexTomlConfigService.cs:218-229
[mcp_servers.uLoopMCP]
command = "node"
args = ['.../server.bundle.js']
env = { "UNITY_TCP_PORT" = "50111" }

The service is capable of inserting this block if it doesn't exist or replacing it if an update is needed.

Sources: Packages/src/Editor/Config/CodexTomlConfigService.cs:109-123, 218-229

Path Resolution

Accurate path resolution is critical for configuration. The static class UnityMcpPathResolver handles all path-related logic.

TypeScript Server Path

The path to the server.bundle.js is essential for the args in the configuration files. The GetTypeScriptServerPath() method finds this file using a prioritized search.

This flowchart illustrates the search logic for server.bundle.js.

Configuration Root (Project vs. Git)

The system can place configuration files in either the Unity project root or the parent Git repository root. This is controlled by the "Add Repository Root" toggle in the McpEditorWindow. UnityMcpPathResolver detects the Git root by searching upwards from the project directory for a .git folder.

• GetProjectRoot(): Returns the Unity project's root directory.
• GetGitRepositoryRoot(): Traverses parent directories to find the .git repository root.
• GetConfigurationRoot(): Returns the Git root if the feature is enabled and the Git root differs from the project root; otherwise, returns the project root.

Sources: Packages/src/Editor/UI/McpEditorWindow.cs:127-133, Packages/src/Editor/Config/UnityMcpPathResolver.cs:135-159, 203-231

Security Configuration

Security settings are configured through the McpEditorWindow and persisted via McpEditorSettings. These settings control access to potentially sensitive Unity Editor operations.

The following options are available in the "Security Settings" section:

• Allow Tests Execution: Enables or disables the run-tests tool.
• Allow Menu Item Execution: Enables or disables the execute-menu-item tool.
• Allow Third Party Tools: Enables or disables custom tools developed by users.

Sources: Packages/src/README.md:195-203, Packages/src/Editor/UI/McpEditorWindow.cs:379-385

Dynamic Code Execution Security

The execute-dynamic-code tool has a dedicated three-tier security model to control its capabilities.

Level	Name	Description
0	Disabled	All dynamic code compilation and execution is forbidden. This is the safest setting.
1	Restricted	(Recommended) Allows execution of most Unity APIs and standard libraries. Blocks dangerous operations like file deletion/writing, network access, and process execution.
2	FullAccess	No restrictions. All assemblies and APIs are accessible. This poses a security risk and should only be used with fully trusted code.

These levels are managed in the McpEditorWindow and stored using McpEditorSettings.SetDynamicCodeSecurityLevel.

Sources: Packages/src/README.md:160-191, Packages/src/Editor/UI/McpEditorWindow.cs:461-464

Settings Persistence

Configuration and UI state are persisted across sessions using two mechanisms: McpEditorSettings (for long-term user preferences) and SessionState (for temporary state within a single Unity Editor session).

• McpEditorSettings: A system that saves data to a JSON file (UserSettings/UnityMcpSettings.json). It is used for settings that should persist after Unity restarts, such as the server port, auto-start preference, and security settings.
• SessionState: A built-in Unity Editor feature for storing data that survives domain reloads (script compilations) but is cleared when the Editor is closed. uLoopMCP uses it to restore the server's running state and UI foldout states after a compile.

Key SessionState keys include:

• uLoopMCP.ServerRunning
• uLoopMCP.ServerPort
• uLoopMCP.SelectedEditorType

Sources: Packages/src/Editor/UI/McpEditorWindow.cs:123, 135-138, 172-175, Packages/src/Editor/Config/McpConstants.cs:98-108