Chapter 5 of 15 7 min beginner

Connect Cursor

mcp.json, stdio, troubleshooting

Verified against a working setup on 2026-08-10

Cursor reads MCP servers from a JSON file and exposes them to its Agent mode. The setup is short; the failure modes are specific enough to be worth knowing in advance.

Where the config lives

Scope	File	Use when
`Global`	`~/.cursor/mcp.json`	One Unity setup across all your projects.
`Project`	`.cursor/mcp.json`	Per-repo, shareable with your team.

Global is usually right for Unity MCP. The server connects to whichever Editor is running, so a per-project file mostly duplicates the same entry.

The config

Cursor uses mcpServers as the top-level key, the same shape as Claude Desktop.

  
json 
{
  "mcpServers": {
    "unity-mcp": {
      "command": "C:\\Users\\you\\.unity\\relay\\relay_win.exe",
      "args": ["--mcp"],
      "env": {}
    }
  }
}
 9 lines

  
json 
{
  "mcpServers": {
    "unityMCP": {
      "type": "stdio",
      "command": "C:\\Users\\you\\.local\\bin\\uvx.exe",
      "args": [
        "--offline",
        "--from", "mcpforunityserver==10.0.0",
        "mcp-for-unity",
        "--transport", "stdio"
      ]
    }
  }
}
 14 lines

  
json 
{
  "mcpServers": {
    "unity-mcp": {
      "command": "/Users/you/.unity/relay/relay",
      "args": ["--mcp"],
      "env": {}
    }
  }
}
 9 lines

Turning it on

1
Write the file
Create ~/.cursor/mcp.json if it does not exist, or add your entry to the existing mcpServers object.
2
Open Cursor Settings → MCP
Your server should be listed. A green indicator means the process started.
3
Enable the server if it is off
Cursor sometimes adds new servers in a disabled state. The toggle is easy to miss.
4
Use Agent mode, not Ask mode
Tools are only available to the agent. In Ask mode the model can talk about Unity but cannot call anything.
5
Verify against the real project
Ask something only your open Editor could answer.
text
List the GameObjects in my currently open Unity scene.
1 lines

The single most common Cursor complaint — "the server is green but there are no tools" — is almost always Ask mode instead of Agent mode. Check that before touching the config.

Cursor-specific gotchas

Symptom	Cause	Fix
`Green, but no tools`	`Ask mode`	Switch to Agent mode.
`Server not listed at all`	`Malformed JSON`	Check backslashes and trailing commas.
`Listed but greyed out`	`Disabled by default`	Toggle it on in Settings → MCP.
`Tools fail every time`	`Unity is closed`	Open the Editor and retry.
`Worked, then stopped`	`Editor recompiling`	Wait for the compile to finish.

That last one catches people out. While Unity recompiles scripts it stops answering, so tool calls fail for a few seconds after every code edit — including edits the model just made. Retrying usually just works.

What to take away

Global config lives at ~/.cursor/mcp.json.
Cursor uses the mcpServers key, like Claude Desktop.
Tools only exist in Agent mode.
New servers can arrive disabled — check the toggle.
Calls fail while Unity is recompiling; retry.