Connecting to LLM Tools

Relevant source files

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

• Packages/src/README.md
• README.md
• Packages/src/ARCHITECTURE.md
• Packages/src/TypeScriptServer~/README.md
• Packages/src/Cli~/src/tests/cli-e2e.test.ts
• SECURITY.md
• Packages/src/TOOL_REFERENCE.md
• Packages/src/TypeScriptServer~/package.json
• Packages/src/ARCHITECTURE_ja.md
• Packages/src/package.json
• Packages/src/Cli~/src/tests/skills-manager.test.ts
• Packages/src/Editor/Config/CodexTomlConfigService.cs

uLoopMCP is designed to let AI agents autonomously compile, test, and operate a Unity project. This is achieved by exposing Unity Editor functionalities as a set of tools that popular LLM environments like Cursor, Claude Code, GitHub Copilot, and Windsurf can orchestrate. The connection between these LLM tools and the Unity Editor is the critical backbone of the system.

There are two primary methods for connecting LLM tools to uLoopMCP: as a Model Context Protocol (MCP) server or by using the standalone uloop Command Line Interface (CLI) tool with a "Skills" system. Both methods allow an AI to drive development loops, but they offer different integration patterns and benefits.

Sources: README.md:15-24, Packages/src/README.md:15-24

System Architecture

The connection architecture consists of three main components that work together to bridge the gap between an LLM tool and the Unity Editor.

Sources: Packages/src/ARCHITECTURE.md:11-18

This diagram shows the high-level architecture and communication flow between the components.

1. LLM Tool (MCP Client): These are development environments like Cursor or Claude Code that can communicate using the Model Context Protocol (MCP). They discover and invoke tools provided by the MCP server.
2. TypeScript Server (Bridge): A Node.js process that acts as the MCP server. It communicates with the LLM tool over stdio and translates MCP requests into JSON-RPC calls for the Unity Editor.
3. Unity Editor (C# TCP Server): The uLoopMCP package running inside Unity hosts a TCP server. This server listens for JSON-RPC commands, executes the corresponding tool (e.g., compile, run-tests), and sends the result back.

Sources: Packages/src/ARCHITECTURE.md:45-50, Packages/src/TypeScriptServer~/README.md:21-25

Connection Methods

1. MCP Server Integration

This is the primary integration method. The TypeScript server is registered with the LLM tool, which then manages its lifecycle.

Automatic Configuration

The easiest way to connect is using the built-in automatic configuration feature.

This flowchart illustrates the automatic setup process initiated from the Unity Editor.

1. In Unity, open Window > uLoopMCP.
2. Press Start Server. The C# TCP server will start on an available port.
3. Select your target LLM tool (e.g., Cursor) from the "LLM Tool Settings" dropdown.
4. Press the Configure {Tool name} button. This automatically writes the necessary configuration file for the selected tool.
5. In the LLM tool, enable the uLoopMCP server.

Sources: README.md:211-218, Packages/src/README.md:211-218

Manual Configuration

If automatic configuration fails or is not desired, you can configure the LLM tool manually by editing its MCP configuration file (e.g., .cursor/mcp.json).

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

Sources: README.md:237-251, Packages/src/README.md:237-251

• command: Must be node, as the bridge is a Node.js application.
• args: The path to the bundled TypeScript server script. The "Configure" button automatically finds the correct path within Library/PackageCache.
• env.UNITY_TCP_PORT: The port number displayed in the uLoopMCP window in Unity.

For tools like Codex and Windsurf, which use a global TOML configuration, the service writes a block to ~/.codex/config.toml.

Sources: README.md:231, Packages/src/Editor/Config/CodexTomlConfigService.cs:10-14

Multi-Instance Support

uLoopMCP supports running multiple Unity instances simultaneously. When a new Unity Editor starts the uLoopMCP server, it automatically finds and binds to an unused port. Each instance can be configured with a separate LLM tool or window by specifying the correct port.

Sources: README.md:260-262, Packages/src/README.md:260-262

2. CLI Tool (uloop) with Skills

As an alternative to MCP server configuration, uLoopMCP provides a standalone CLI tool named uloop. This method is designed for "Skills"-compatible LLM tools like Claude Code.

Benefits of using the CLI:

• No MCP configuration files are needed.
• The LLM tool automatically discovers and invokes Unity operations via shell commands.
• More efficient with LLM context, as the tool definitions are not part of the prompt.
• Easily operate multiple Unity instances using the --port flag.

Sources: README.md:268-278, Packages/src/README.md:268-278

Quick Start

1. Install the CLI globally:

   npm install -g uloop-cli
   

2. Install the Skills: Navigate to your project directory and run:

   # For project-level skills with Claude Code
   uloop skills install --claude
   

   This command finds all bundled and project-specific SKILL.md files and installs them for the LLM tool to use.

Sources: README.md:283-292, Packages/src/README.md:283-292

Once skills are installed, the LLM can directly invoke Unity functionality.

User Instruction	Skill Used by LLM
"Fix the compile errors"	/uloop-compile
"Run the tests and tell me why they failed"	/uloop-run-tests + /uloop-get-logs
"Check the scene hierarchy"	/uloop-get-hierarchy
"Search for prefabs"	/uloop-unity-search

Sources: README.md:296-306, Packages/src/README.md:296-306

The uloop CLI communicates directly with the Unity C# TCP server, bypassing the TypeScript MCP bridge.

This sequence diagram shows the CLI interaction flow.

Security Considerations

Connecting external tools to the Unity Editor introduces security considerations that developers must be aware of.

Setting	Description	Default	Recommendation
Allow Tests Execution	Enables the run-tests tool.	Disabled	Enable only when needed for CI or AI-driven TDD.
Allow Menu Item Execution	Enables the execute-menu-item tool.	Disabled	Enable with caution, as it can run any editor script.
Allow Third Party Tools	Enables custom, project-specific tools.	Disabled	Enable only for trusted, audited extension tools.
Dynamic Code Security Level	Controls execute-dynamic-code permissions.	Level 0 (Disabled)	Use Level 1 (Restricted) for most AI tasks. Use Level 2 (FullAccess) only with fully trusted code.

Sources: README.md:188-204, SECURITY.md:29-32

When using the uloop CLI with Claude Code in its sandboxed environment, you must allow localhost network connections by adding the following to your project's .claude/settings.local.json:

{
  "sandbox": {
    "network": {
      "allowLocalBinding": true
    }
  }
}

Warning: This setting allows Claude Code to access all services running on your machine's localhost, not just uLoopMCP.

Sources: README.md:347-368, Packages/src/README.md:347-368

Summary

uLoopMCP offers two robust and flexible methods for connecting LLM-powered tools to the Unity Editor. The MCP Server integration provides a deep, protocol-based connection managed by the LLM tool itself, ideal for environments like Cursor. The uloop CLI with Skills offers a lightweight, command-based approach that is context-efficient and simple to set up for skill-aware agents like Claude Code. Both pathways empower AI to perform complex development, testing, and automation tasks directly within a Unity project, enabling a more autonomous development loop.

Sources: README.md:15-24, Packages/src/README.md:15-24