CoplayDev/unity-mcp · error · UnityConnectionError

Cannot connect to Unity MCP server at {cfg.host}:{cfg.port}.

Error message

Cannot connect to Unity MCP server at {cfg.host}:{cfg.port}. Make sure the server is running and Unity is connected.
Error: {e}

What it means

Thrown by send_command() when httpx raises a ConnectError posting to http://<host>:<port>/api/command. A ConnectError means the TCP connection to the Python MCP server could not be established — the server process is not listening, or host/port are wrong. It surfaces host, port, and the underlying transport error for diagnosis.

Source

Thrown at Server/src/cli/utils/connection.py:111

    payload = {
        "type": command_type,
        "params": params,
    }

    if cfg.unity_instance:
        payload["unity_instance"] = cfg.unity_instance

    try:
        async with httpx.AsyncClient() as client:
            response = await client.post(
                url,
                json=payload,
                timeout=timeout or cfg.timeout,
            )
            response.raise_for_status()
            return response.json()
    except httpx.ConnectError as e:
        raise UnityConnectionError(
            f"Cannot connect to Unity MCP server at {cfg.host}:{cfg.port}. "
            f"Make sure the server is running and Unity is connected.\n"
            f"Error: {e}"
        )
    except httpx.TimeoutException:
        raise UnityConnectionError(
            f"Connection to Unity timed out after {timeout or cfg.timeout}s. "
            f"Unity may be busy or unresponsive."
        )
    except httpx.HTTPStatusError as e:
        raise UnityConnectionError(
            f"HTTP error from server: {e.response.status_code} - {e.response.text}"
        )
    except Exception as e:
        raise UnityConnectionError(f"Unexpected error: {e}")


def run_command(

View on GitHub (pinned to c21bf496bc)

Solutions

1. Start the MCP server in HTTP mode and confirm it is listening on the configured host:port.
2. Verify UNITY_MCP_HOST and UNITY_MCP_HTTP_PORT match the server's bind address.
3. Check the server process is alive and not crashed (logs), and that no firewall blocks localhost.
4. If using stdio transport, remember the CLI HTTP path does not apply — use the MCP client instead.

Example fix

# before
# server not running; CLI call fails
unity-mcp texture list
# after
# start server, then run CLI
python -m server  # (HTTP mode)
unity-mcp texture list

import socket
with socket.socket() as s:
    s.settimeout(1)
    try:
        s.connect((cfg.host, cfg.port))
        reachable = True
    except OSError:
        reachable = False
if not reachable:
    raise RuntimeError("MCP server not reachable")

try:
    return await send_command(cmd, params)
except UnityConnectionError as e:
    if "Cannot connect" in str(e):
        print_error("Start the MCP server, then retry.")
    raise

When it happens

Trigger: Running a CLI command while the MCP server is not started, is bound to a different host/port, or is firewalled. Also when UNITY_MCP_HOST/UNITY_MCP_HTTP_PORT point at the wrong address.

Common situations: Server not launched yet, crashed, or running under stdio mode (which uses a legacy TCP bridge, not the HTTP endpoint). Mismatched host/port between CLI and server, or a Docker/port-forward issue.

Related errors

• Connection to Unity timed out after {timeout or cfg.timeout}
• HTTP error from server: {e.response.status_code} - {e.respon
• Unexpected error: {e}
• fal {phase} failed (status={res?.Status}): {detail}
• fal {phase} failed (status={res?.Status}): {detail}

AI-assisted analysis of CoplayDev/unity-mcp@c21bf496bc (2026-08-13). Data as JSON: /api/errors/08512a788952fd3d. Report an issue: GitHub.