{"record":{"id":"08512a788952fd3d","repo":"CoplayDev/unity-mcp","slug":"cannot-connect-to-unity-mcp-server-at-cfg-host","errorCode":null,"errorMessage":"Cannot connect to Unity MCP server at {cfg.host}:{cfg.port}. Make sure the server is running and Unity is connected.\nError: {e}","messagePattern":"Cannot connect to Unity MCP server at (.+?):(.+?)\\. Make sure the server is running and Unity is connected\\.\nError: (.+?)","errorType":"exception","errorClass":"UnityConnectionError","httpStatus":null,"severity":"error","filePath":"Server/src/cli/utils/connection.py","lineNumber":111,"sourceCode":"    payload = {\n        \"type\": command_type,\n        \"params\": params,\n    }\n\n    if cfg.unity_instance:\n        payload[\"unity_instance\"] = cfg.unity_instance\n\n    try:\n        async with httpx.AsyncClient() as client:\n            response = await client.post(\n                url,\n                json=payload,\n                timeout=timeout or cfg.timeout,\n            )\n            response.raise_for_status()\n            return response.json()\n    except httpx.ConnectError as e:\n        raise UnityConnectionError(\n            f\"Cannot connect to Unity MCP server at {cfg.host}:{cfg.port}. \"\n            f\"Make sure the server is running and Unity is connected.\\n\"\n            f\"Error: {e}\"\n        )\n    except httpx.TimeoutException:\n        raise UnityConnectionError(\n            f\"Connection to Unity timed out after {timeout or cfg.timeout}s. \"\n            f\"Unity may be busy or unresponsive.\"\n        )\n    except httpx.HTTPStatusError as e:\n        raise UnityConnectionError(\n            f\"HTTP error from server: {e.response.status_code} - {e.response.text}\"\n        )\n    except Exception as e:\n        raise UnityConnectionError(f\"Unexpected error: {e}\")\n\n\ndef run_command(","sourceCodeStart":93,"sourceCodeEnd":129,"githubUrl":"https://github.com/CoplayDev/unity-mcp/blob/c21bf496bca87d54e75bad048563c3adb1782081/Server/src/cli/utils/connection.py#L93-L129","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Start the MCP server in HTTP mode and confirm it is listening on the configured host:port.","Verify UNITY_MCP_HOST and UNITY_MCP_HTTP_PORT match the server's bind address.","Check the server process is alive and not crashed (logs), and that no firewall blocks localhost.","If using stdio transport, remember the CLI HTTP path does not apply — use the MCP client instead."],"exampleFix":"# before\n# server not running; CLI call fails\nunity-mcp texture list\n# after\n# start server, then run CLI\npython -m server  # (HTTP mode)\nunity-mcp texture list","handlingStrategy":"try-catch","validationCode":"import socket\nwith socket.socket() as s:\n    s.settimeout(1)\n    try:\n        s.connect((cfg.host, cfg.port))\n        reachable = True\n    except OSError:\n        reachable = False\nif not reachable:\n    raise RuntimeError(\"MCP server not reachable\")","typeGuard":null,"tryCatchPattern":"try:\n    return await send_command(cmd, params)\nexcept UnityConnectionError as e:\n    if \"Cannot connect\" in str(e):\n        print_error(\"Start the MCP server, then retry.\")\n    raise","preventionTips":["Start the HTTP server before running CLI commands.","Keep UNITY_MCP_HOST/PORT aligned with the server bind address."],"tags":["cli","network","connection","http"],"backgroundTag":null,"analyzedSha":"c21bf496bca87d54e75bad048563c3adb1782081","analyzedAt":"2026-08-13T17:36:56.095Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}