Bug: Unity MCP can make Codex Desktop lose the whole MCP tool surface on Windows (`spawn ENAMETOOLONG` / oversized tool registry)

[JESVN]

Bug: Unity MCP can make Codex Desktop lose the whole MCP tool surface on Windows (spawn ENAMETOOLONG / oversized tool registry)

Summary

When unity-mcp-server is registered as an MCP server in a Codex Desktop project on Windows, Codex may lose the entire MCP tool surface for the session. This includes unrelated MCP servers such as context-mode, codegraph, and node_repl.

The failure is deterministic in my setup:

• Remove only the Unity MCP server entry and restart Codex: other MCP servers work.
• Add the Unity MCP server entry back and restart Codex: the MCP tool surface becomes unavailable or partially unavailable.

After further diagnosis, this appears to be caused primarily by the size/shape of the Unity MCP tool registry returned by tools/list, not by Unity Editor connectivity. Codex Desktop logs show a Windows process spawn failure:

worker_rpc_response_error errorMessage="spawn ENAMETOOLONG"

This suggests that Codex is passing an aggregate MCP/tool payload through a Windows process boundary, and Unity MCP's exposed tools push the payload over a command-line/environment-size limit. A local mitigation that reduced Unity's direct exposed tool surface and compacted schemas made Unity MCP coexist with other MCP servers again.

Affected components

• Unity MCP Node server: AnkleBreaker-Studio/unity-mcp-server
• Unity package/plugin: AnkleBreaker-Studio/unity-mcp-plugin
• MCP client: Codex Desktop on Windows
• Transport: MCP stdio

Environment

• OS: Windows
• Unity version: 6000.3.9f1
• Unity MCP package source in Packages/manifest.json:
  • https://github.com/AnkleBreaker-Studio/unity-mcp-plugin.git
• Unity MCP package cache observed locally:
  • Library/PackageCache/com.anklebreaker.unity-mcp@55cd393fe53c
• Unity MCP server package metadata observed locally:
  • package.json version: 2.30.0
  • MCP initialize serverInfo.version: 2.26.0
• Unity bridge port range: 7890-7899
• Active Unity instance observed during tests:
  • port: 7891
  • project path matched the current Unity project

Minimal MCP config that triggers the issue

The project-local Codex config contains a Unity MCP server entry equivalent to:

[mcp_servers.unity]
command = "node"
args = ["<project>/mcp/unity-mcp-server/src/index.js"]
startup_timeout_sec = 30
tool_timeout_sec = 120

[mcp_servers.unity.env]
UNITY_BRIDGE_HOST = "127.0.0.1"
UNITY_BRIDGE_PORT = "7890"
UNITY_PORT_RANGE_START = "7890"
UNITY_PORT_RANGE_END = "7899"

Other MCP servers are also configured, for example:

• context-mode
• codegraph
• node_repl

Steps to reproduce

1. Start Unity Editor with the Unity MCP plugin enabled.
2. Confirm Unity MCP bridge is listening on one of 7890-7899.
3. Add the Unity MCP server entry above to Codex's project-local MCP config.
4. Restart Codex Desktop / open a new conversation for the project.
5. Try to use any MCP tool, including non-Unity tools.

Actual behavior

• Codex Desktop opens the conversation, but MCP tools become unavailable or partially unavailable.
• Non-Unity MCP tools that normally work are not exposed or not routed as tools.
• Example symptom: context-mode functionality is no longer available through the MCP tool surface.
• Removing only the Unity MCP server entry and restarting Codex restores the other MCP servers.
• The Unity MCP row may appear connected but unavailable in Codex settings; UI controls for that row may also become unresponsive.

Expected behavior

• Registering Unity MCP should not make unrelated MCP servers unavailable.
• Unity MCP should expose a client-safe tools/list response that does not exceed Windows/Codex payload limits.
• If Unity Editor, context, or a specific Unity tool fails, only that Unity operation should fail; the whole MCP registry should remain usable.

Important evidence

1. Codex Desktop logs show spawn ENAMETOOLONG

Recent Codex Desktop logs contain:

warning [electron-message-handler] worker_rpc_response_error errorMessage="spawn ENAMETOOLONG"

The issue appears only when Unity MCP is registered. This strongly points to an oversized aggregate tool/server payload being passed through a Windows process boundary.

2. Unity MCP starts and responds to MCP in isolation

A direct stdio MCP probe against src/index.js succeeds:

{
  "ok": true,
  "toolCount": 79,
  "stderrTail": [
    "[MCP] Tool tiers: 68 core + 254 advanced (via unity_advanced_tool) = 322 total, 79 exposed",
    "Unity MCP Server running on stdio"
  ]
}

So the server is not simply crashing at startup.

3. tools/list payload is large

Measured locally before mitigation:

79 exposed tools
tools/list payload: ~53 KB

After only schema/description compaction while keeping 79 exposed tools:

79 exposed tools
tools/list payload: ~24.9 KB

After reducing the direct exposed surface and keeping advanced tools behind unity_advanced_tool:

37 exposed tools
296 advanced tools still reachable through unity_advanced_tool
tools/list payload: ~11.7 KB

This compact mode made Unity MCP load and coexist with other MCP servers in Codex Desktop.

4. Some exposed schemas are not strict-client friendly

One concrete issue observed locally:

// src/tools/editor-tools.js
value: {
  description: "Value to set (type depends on property). For ObjectReference: ..."
}

This property has no explicit JSON Schema shape (type, $ref, enum, anyOf, etc.). Strict MCP clients or clients converting MCP tools to function-call/tool definitions may reject the tool list or fail downstream.

A local schema normalization pass fixed this class of issue by ensuring exposed schemas are explicit and compact.

5. /api/context returns HTTP 500

Calling unity_get_project_context through the MCP server can fail against Unity's /api/context endpoint:

Context request failed: HTTP 500

The project contains valid context files under:

Assets/MCP/Context/

A local Node-side fallback that reads these markdown files directly made unity_get_project_context and MCP resources/list/read usable again. This is probably a separate plugin-side issue, but it should be isolated so context failures cannot affect MCP startup or tool discovery.

Local mitigation that worked

I tested a local patch with these changes:

1. Compact the direct MCP tool surface by default:
   • expose only essential Unity tools directly;
   • keep all specialized tools available through unity_advanced_tool;
   • provide an opt-out env var such as UNITY_MCP_FULL_TOOLS=1 to restore broad direct exposure.
2. Compact tools/list output:
   • shorten top-level tool descriptions;
   • remove nested parameter descriptions from inputSchema;
   • keep names, types, required fields, and object structure.
3. Normalize schemas before returning tools/list:
   • every property has an explicit shape;
   • object schemas have properties;
   • avoid unsupported open-ended object schemas for strict clients.
4. Avoid automatic large context injection on the first tool call by default.
   • keep explicit unity_get_project_context and MCP resources instead.
5. Add filesystem fallback for context:
   • if /api/context fails, read Assets/MCP/Context/*.md from the selected/discovered project path.

After this mitigation:

Unity MCP direct tools: 37
Unity advanced tools: 296
Total Unity capability remains: 322 tools
tools/list payload: ~11.7 KB

Validation after mitigation:

• Unity MCP loads in Codex Desktop.
• context-mode, codegraph, and node_repl remain usable at the same time.
• unity_list_instances, unity_editor_ping, unity_editor_state, unity_project_info, unity_scene_info, unity_get_project_context, unity_get_compilation_errors, and unity_console_log work.
• Creating/querying/updating/deleting a temporary Cube works.
• unity_advanced_tool can call a non-direct tool such as unity_selection_get successfully.

Requested changes upstream

Please consider adding an upstream client-compatible mode, preferably enabled by default for strict/Windows clients:

1. Compact direct exposed tools

   • Keep a small direct set for common operations.
   • Keep the rest behind unity_advanced_tool.
   • Provide an env/config switch to restore full direct exposure.

2. Shrink and normalize tools/list

   • Do not return large nested descriptions by default.
   • Ensure strict JSON Schema compatibility for all exposed inputSchema objects.
   • Add an automated schema validation test for the generated tool list.

3. Fix or isolate project context endpoint failures

   • Fix Unity plugin /api/context HTTP 500.
   • Ensure context failures never affect initialize, tools/list, or unrelated resources/tools.
   • Consider Node-side filesystem fallback for Assets/MCP/Context.

4. Version consistency

   • Align package.json version (2.30.0 observed) with MCP serverInfo.version (2.26.0 observed), or clarify why they intentionally differ.

Impact

Without this mitigation, Unity MCP can make Codex Desktop lose unrelated MCP tools in the same project/session. This makes the server difficult to use in Codex even though the Unity bridge itself is reachable.

With the compact/normalized tool registry, the MCP server works and still retains access to advanced Unity functionality through the advanced dispatcher.