How to Troubleshoot Connection Problems with Unity MCP: Complete Diagnostics Guide

Unity MCP connection issues are typically resolved by verifying TCP port settings, enabling UDP discovery in McpSettings, checking firewall rules for ports 27182-27183, and inspecting detailed logs in the Unity console.

Unity MCP (Model Context Protocol) enables the Unity Editor to communicate with an external TypeScript MCP server via TCP socket. According to the isuzu-shiranui/unitymcp source code, most connection failures stem from network configuration mismatches, firewall blocks, or incorrect host/port settings. This guide walks through the exact connection flow implemented in Editor/Core/McpServer.cs and provides actionable fixes for common failure modes.

Understanding the Unity MCP Connection Architecture

The connection system follows a four-stage lifecycle defined in Editor/Core/McpServer.cs. Understanding these stages helps pinpoint exactly where the handshake breaks down.

Server Configuration and UDP Discovery

Connection parameters are stored in Editor/Settings/McpSettings.cs. The client uses two discovery modes:

• Static configuration – McpSettings.host and McpSettings.port (default 27182) define the target address.
• UDP discovery – When McpSettings.useUdpDiscovery is enabled, the client listens on McpSettings.udpDiscoveryPort (default 27183) for broadcast messages from the TypeScript server. Upon receiving a broadcast, the client automatically updates host and port values.

In McpServer.cs (lines 59-71), the UDP listener runs on a background thread and updates connection targets dynamically when a valid broadcast is detected.

Connection Lifecycle and Retry Logic

The McpServer.Start() method spawns a background thread that repeatedly invokes TryConnect() until a TCP handshake succeeds. As implemented in McpServer.cs (lines 34-52), the system uses exponential back-off between attempts:

• Initial reconnectDelay escalates toward maxReconnectDelay with each failure
• Connection state is surfaced in the UI via Editor/Settings/McpSettingsProvider.cs (lines 33-41), showing "Connected", "Connecting…", or "Disconnected"

Common Unity MCP Connection Symptoms and Fixes

Symptom	Root Cause	Resolution
"● Disconnected" with no console output	TCP server unreachable or not running; wrong host/port	Verify the TypeScript MCP server is listening using netstat -an or the server's console output. Confirm McpSettings.host matches the server address.
"● Connecting… persists indefinitely	UDP discovery disabled with incorrect static host/port, or firewall blocking TCP	Enable Use UDP Discovery in Preferences, or manually correct the Host/Port fields. Check firewall rules for the configured TCP port.
Repeated "Failed to connect… Will retry"	Firewall blocking outbound TCP (port 27182) or inbound UDP (port 27183)	Open both ports for bidirectional traffic. On macOS, add Unity Editor to Allowed Apps; on Windows, create inbound/outbound rules for ports 27182-27183.
No UDP broadcast received	Server not broadcasting, mismatched discovery ports, or network multicast disabled	Ensure the server's udpDiscoveryPort matches McpSettings.udpDiscoveryPort. Verify the network permits UDP traffic on that port.
Missing diagnostic details	McpSettings.detailedLogs set to false	Enable Detailed Logs in Edit → Preferences → Unity MCP to view UDP listener status and connection retry messages.

Step-by-Step Troubleshooting Checklist

Follow this sequence to isolate Unity MCP connection problems:

1. Open Unity MCP Settings – Navigate to Edit → Preferences → Unity MCP to view the McpSettingsProvider UI.

2. Verify Connection Method – Check the Use UDP Discovery checkbox. If disabled, confirm the Host and Port values match your TypeScript server exactly.

3. Enable Detailed Logging – Tick Detailed Logs to force McpServer to emit verbose Debug.Log messages for every connection attempt.

4. Monitor Unity Console – Watch for these specific log patterns from McpServer:

   • [McpServer] Started UDP listener … – Confirms the discovery thread is active.
   • [McpServer] Detected MCP TypeScript server … – Indicates successful UDP broadcast reception.
   • [McpServer] Connected to MCP TypeScript server … – Signals successful TCP handshake completion.

5. Validate External Server – Confirm the TypeScript MCP process is running and bound to the expected TCP port (default 27182).

6. Inspect Firewall Rules – On both the Unity Editor machine and server host, allow:

   • Outbound TCP to the MCP port
   • Inbound UDP on the discovery port (27183)

7. Test Programmatically – Use the diagnostic script below to trigger connection logic outside the UI and verify raw socket behavior.

Diagnostic Code Examples

Programmatically Test Connection Status

Run this Editor script to bypass the UI and inspect raw connection state. This invokes the same McpServer logic used by the preferences panel.

using UnityEditor;
using UnityEngine;
using UnityMCP.Editor.Core;

public static class McpDiagnostics {
    private static McpServer server;

    [MenuItem("MCP/Diagnostics/Start Client")]
    public static void StartClient() {
        if (server == null) {
            server = new McpServer(); // Reads McpSettings automatically
            McpServiceManager.Instance.RegisterService(server);
        }
        server.Start(); // Begins TryConnect loop with exponential back-off
        Debug.Log($"MCP initialized – Running={server.IsRunning}");
    }

    [MenuItem("MCP/Diagnostics/Stop Client")]
    public static void StopClient() {
        server?.Stop();
        Debug.Log("MCP connection terminated");
    }

    [MenuItem("MCP/Diagnostics/Print Status")]
    public static void PrintStatus() {
        if (server == null) {
            Debug.LogWarning("MCP server not initialized");
            return;
        }
        Debug.Log($"Running={server.IsRunning}, Connected={server.IsConnected}");
        if (server.IsConnected) {
            Debug.Log($"ClientId={server.ClientId}, ConnectedSince={server.ConnectedSince}");
        }
    }
}

Override Host and Port at Runtime

When UDP discovery fails, force a manual connection to test specific endpoints:

var customPort = 30000; // Replace with your server's actual port
var manualServer = new McpServer(customPort); // Constructor overload overrides McpSettings
McpServiceManager.Instance.RegisterService(manualServer);
manualServer.Start();

Enable Runtime Detailed Logging

Toggle verbose output without restarting the Editor:

McpSettings.instance.detailedLogs = true;
McpSettings.instance.Save(); // Persists to EditorPrefs

After enabling, the next TryConnect iteration will print step-by-step diagnostics to the Unity console, including UDP listener initialization and TCP retry timestamps.

Summary

• Unity MCP connects via TCP socket with optional UDP discovery on ports 27182 (TCP) and 27183 (UDP).
• Connection state is managed in Editor/Core/McpServer.cs with exponential back-off retry logic.
• Most failures are resolved by enabling McpSettings.useUdpDiscovery, verifying firewall rules, or correcting static host/port values.
• Detailed logs in McpSettings.detailedLogs reveal whether the UDP listener starts and if TCP handshakes succeed.
• Programmatic testing via new McpServer() bypasses UI issues and confirms raw socket connectivity.

Frequently Asked Questions

Why does Unity MCP show "Connecting..." indefinitely?

This indicates the TCP handshake never completes. The client at McpServer.cs lines 34-52 is likely retrying with exponential back-off but never receiving an ACK. Causes include: the TypeScript server not running, firewall blocking outbound TCP on the configured port, or incorrect host/port when UDP discovery is disabled. Enable Detailed Logs to confirm which stage stalls.

How do I enable detailed logging for Unity MCP?

Open Edit → Preferences → Unity MCP and tick Detailed Logs, or run McpSettings.instance.detailedLogs = true; in an Editor script. This persists to EditorPrefs and forces McpServer to emit [McpServer] prefixed logs for UDP listener status, broadcast reception, and TCP connection attempts.

What ports need to be open for Unity MCP to work?

The default configuration requires TCP port 27182 for the MCP protocol communication and UDP port 27183 for discovery broadcasts. Both must be open for bidirectional traffic if using UDP discovery; only the TCP port is required if using static host configuration. These defaults are defined in Editor/Settings/McpSettings.cs.

Can I manually specify the host and port instead of using UDP discovery?

Yes. In the Preferences UI, untick Use UDP Discovery and enter the exact IP address in Host and port number in Port. Alternatively, instantiate McpServer with a port constructor overload: new McpServer(30000) overrides settings and attempts connection to the specified port immediately, bypassing the UDP discovery phase entirely.

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