Environment:
- Cursor version 2.6.22
- Unity MCP version 9.6.4 with local HTTP transport. Everything else is default
- Unity 6.3.10f1
- Package: com.coplaydev.unity-mcp from https://github.com/CoplayDev/unity-mcp.git
- OS: Windows 11
Summary:
When driving the Unity MCP from Cursor’s agent, several tools either do not resolve or fail JSON parsing before reaching Unity. The same MCP instructions reference resources like mcpforunity://instances and tools like manage_scene / manage_gameobject / unity_reflect, but the actual invocations from the agent layer produced the errors below.
- Resource fetch — tool name not found
Invocation (agent used): mcp_unityMCP_fetch_mcp_resource with a Unity resource URI (e.g. mcpforunity://instances).
Error:
Tool not found: mcp_unityMCP_fetch_mcp_resource
Notes:
The combined “available tools” list for the session included a generic fetch_mcp_resource (no mcp_unityMCP_ prefix), while the agent attempted a prefixed name.
MCP instructions explicitly say to read mcpforunity://custom-tools and mcpforunity://instances first; without a working, documented mapping from documented URI → exact tool name the client must call, integrations break.
Please document the canonical client-side tool id for reading MCP resources for this server, and whether Cursor should call fetch_mcp_resource vs a Unity-prefixed alias.
- manage_scene — invalid JSON (malformed arguments)
Error (verbatim):
Unexpected token 'A', "{"path": Assets, "a"... is not valid JSON
Observed pattern: The fragment looks like JSON where string values are not quoted (e.g. Assets instead of "Assets"), or the whole argument payload was not passed as a single JSON object.
Please publish a strict JSON schema (or example payloads) for manage_scene (required keys, types).
If the Cursor MCP adapter stringifies or merges parameters incorrectly, clarify whether the server or client should validate/normalize arguments before parse.
- unity_reflect — invalid JSON
Error (verbatim):
Error: Unexpected token 'X', ..." "query": XRHandSubs"... is not valid JSON
Context: Call was intended to search or inspect Unity types (e.g. XR Hands APIs).
Hypothesis: Truncated argument, broken escaping inside the query string, or non-JSON concatenated into the tool-args buffer.
Please confirm how multi-word string parameters must be escaped when embedded in the MCP JSON envelope; add a minimal working example for unity_reflect with action + query.
- manage_gameobject — invalid JSON (repeated)
Error (verbatim):
Unexpected token 'c', ...""action": create, "n"... is not valid JSON
Observed pattern: Suggests the parser received something like "action": create (unquoted create) or a double-quoted outer string containing inner quotes (""action": create...), i.e. double-encoded or non-JSON tool parameters.
Impact: Cannot create/instantiate prefabs or modify the scene from the agent; all automation falls back to manual file edits.
Please validate arguments with a clear error: which tool, which parameter, raw payload snippet (redacted) and document the exact shape for manage_gameobject create (e.g. source_prefab_path, parent, position types).
- Process note (for Cursor + MCP integration)
After several failures, the agent retried similar calls and hit a loop / rate-limit style reminder. That suggests transient JSON errors are indistinguishable from logic errors, so the agent cannot self-correct without a machine-readable error (e.g. JSON Schema validation result).
Please return structured errors: { "error": "invalid_json", "position": ..., "snippet": "..." } instead of a single generic parse message.
If tool names are namespaced (mcp_unityMCP_*), expose that exact list via MCP discovery so agents do not guess names.
- What would have helped (acceptance criteria)
One “hello unity” doc section: list exact tool ids + one copy-paste JSON example per high-traffic tool (manage_scene, manage_gameobject, read_console, unity_reflect, resource fetch).
Argument validation before Unity execution, with parameter-level error messages.
Resource API: single documented way to read mcpforunity://instances and mcpforunity://custom-tools from Cursor.
Disclaimer (honest scope)
Some failures may be Cursor’s MCP argument serialization, not the Unity plugin.
Environment:
Summary:
When driving the Unity MCP from Cursor’s agent, several tools either do not resolve or fail JSON parsing before reaching Unity. The same MCP instructions reference resources like mcpforunity://instances and tools like manage_scene / manage_gameobject / unity_reflect, but the actual invocations from the agent layer produced the errors below.
Invocation (agent used): mcp_unityMCP_fetch_mcp_resource with a Unity resource URI (e.g. mcpforunity://instances).
Error:
Tool not found: mcp_unityMCP_fetch_mcp_resource
Notes:
The combined “available tools” list for the session included a generic fetch_mcp_resource (no mcp_unityMCP_ prefix), while the agent attempted a prefixed name.
MCP instructions explicitly say to read mcpforunity://custom-tools and mcpforunity://instances first; without a working, documented mapping from documented URI → exact tool name the client must call, integrations break.
Please document the canonical client-side tool id for reading MCP resources for this server, and whether Cursor should call fetch_mcp_resource vs a Unity-prefixed alias.
Error (verbatim):
Unexpected token 'A', "{"path": Assets, "a"... is not valid JSON
Observed pattern: The fragment looks like JSON where string values are not quoted (e.g. Assets instead of "Assets"), or the whole argument payload was not passed as a single JSON object.
Please publish a strict JSON schema (or example payloads) for manage_scene (required keys, types).
If the Cursor MCP adapter stringifies or merges parameters incorrectly, clarify whether the server or client should validate/normalize arguments before parse.
Error (verbatim):
Error: Unexpected token 'X', ..." "query": XRHandSubs"... is not valid JSON
Context: Call was intended to search or inspect Unity types (e.g. XR Hands APIs).
Hypothesis: Truncated argument, broken escaping inside the query string, or non-JSON concatenated into the tool-args buffer.
Please confirm how multi-word string parameters must be escaped when embedded in the MCP JSON envelope; add a minimal working example for unity_reflect with action + query.
Error (verbatim):
Unexpected token 'c', ...""action": create, "n"... is not valid JSON
Observed pattern: Suggests the parser received something like "action": create (unquoted create) or a double-quoted outer string containing inner quotes (""action": create...), i.e. double-encoded or non-JSON tool parameters.
Impact: Cannot create/instantiate prefabs or modify the scene from the agent; all automation falls back to manual file edits.
Please validate arguments with a clear error: which tool, which parameter, raw payload snippet (redacted) and document the exact shape for manage_gameobject create (e.g. source_prefab_path, parent, position types).
After several failures, the agent retried similar calls and hit a loop / rate-limit style reminder. That suggests transient JSON errors are indistinguishable from logic errors, so the agent cannot self-correct without a machine-readable error (e.g. JSON Schema validation result).
Please return structured errors: { "error": "invalid_json", "position": ..., "snippet": "..." } instead of a single generic parse message.
If tool names are namespaced (mcp_unityMCP_*), expose that exact list via MCP discovery so agents do not guess names.
One “hello unity” doc section: list exact tool ids + one copy-paste JSON example per high-traffic tool (manage_scene, manage_gameobject, read_console, unity_reflect, resource fetch).
Argument validation before Unity execution, with parameter-level error messages.
Resource API: single documented way to read mcpforunity://instances and mcpforunity://custom-tools from Cursor.
Disclaimer (honest scope)
Some failures may be Cursor’s MCP argument serialization, not the Unity plugin.