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

> Troubleshoot Unity MCP connection problems by verifying TCP ports, enabling UDP discovery, checking firewalls, and inspecting Unity console logs for quick resolution.

- Repository: [いすず/unitymcp](https://github.com/isuzu-shiranui/unitymcp)
- Tags: how-to-guide
- Published: 2026-03-04

---

**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`](https://github.com/isuzu-shiranui/unitymcp/blob/main/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`](https://github.com/isuzu-shiranui/unitymcp/blob/main/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`](https://github.com/isuzu-shiranui/unitymcp/blob/main/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`](https://github.com/isuzu-shiranui/unitymcp/blob/main/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`](https://github.com/isuzu-shiranui/unitymcp/blob/main/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`](https://github.com/isuzu-shiranui/unitymcp/blob/main/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.

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

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

```csharp
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`](https://github.com/isuzu-shiranui/unitymcp/blob/main/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`](https://github.com/isuzu-shiranui/unitymcp/blob/main/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`](https://github.com/isuzu-shiranui/unitymcp/blob/main/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.