Connect Cursor
mcp.json, stdio, troubleshooting
Chapter 5 of 15 7 min read beginner Verified on a working setup, 10 Aug 2026
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. |
The config
Cursor uses mcpServers as the top-level key, the same shape as Claude Desktop.
{
"mcpServers": {
"unity-mcp": {
"command": "C:\\Users\\you\\.unity\\relay\\relay_win.exe",
"args": ["--mcp"],
"env": {}
}
}
}{
"mcpServers": {
"unityMCP": {
"type": "stdio",
"command": "C:\\Users\\you\\.local\\bin\\uvx.exe",
"args": [
"--offline",
"--from", "mcpforunityserver==10.0.0",
"mcp-for-unity",
"--transport", "stdio"
]
}
}
}{
"mcpServers": {
"unity-mcp": {
"command": "/Users/you/.unity/relay/relay",
"args": ["--mcp"],
"env": {}
}
}
}Turning it on
- 1 Write the file
Create
~/.cursor/mcp.jsonif it does not exist, or add your entry to the existingmcpServersobject. - 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.
textList the GameObjects in my currently open Unity scene.
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. |
What to take away
- Global config lives at
~/.cursor/mcp.json. - Cursor uses the
mcpServerskey, like Claude Desktop. - Tools only exist in Agent mode.
- New servers can arrive disabled — check the toggle.
- Calls fail while Unity is recompiling; retry.