Connecting AI clients — Unity · AI Game Developer Wiki

This page explains how an AI client reaches the Unity Editor, which endpoint and sign-in it uses, and how to configure each supported agent from the AI Game Developer window, from unity-mcp-cli, or by hand.

Two ways to connect

Your AI client never talks to Unity directly. Both connect to an MCP server, and the server routes tool calls to the Editor over a SignalR connection.

	Cloud (default)	Custom (local)
Server	The hosted endpoint `https://ai-game.dev/mcp`	`gamedev-mcp-server`, downloaded and started by the plugin
Editor connection	The plugin connects to ai-game.dev	The plugin connects to `http://localhost:<port>`
Client endpoint	`https://ai-game.dev/mcp/p/<pin>` (pinned) or `https://ai-game.dev/mcp`	`http://localhost:<port>`, or the server binary over stdio
Sign-in	ai-game.dev account (OAuth device flow)	None, ai-game.dev OAuth, or a shared token
Works offline	No	Yes, with `none` or `token` authorization

Pick the mode with the Connection switch (Custom / Cloud) in the AI Game Developer window. Configuration covers the local server settings.

Pinned URLs

The base endpoint https://ai-game.dev/mcp routes to one of your connected editors by fallback. That is fine with a single open project, but ambiguous with several.

A pinned URL, https://ai-game.dev/mcp/p/<pin>, always routes to one project's Editor. The pin is derived from the project's identity. The window's Configure button and unity-mcp-cli setup-mcp write the pinned URL by default; setup-mcp --no-pin writes the base URL instead. For the stdio transport, the pin is passed as a project=<pin> argument.

The Editor, the CLI and the desktop app share one machine-wide sign-in in ~/.ai-game-dev/credentials.json. Sign in once in any of them:

In the window: Cloud mode, then Authorize, then approve the code in your browser.
In a terminal: unity-mcp-cli login.
In the AI Game Dev app: Sign in.

Tokens refresh in the background. Revoke in the window signs out every AI Game Dev tool on the machine (all engine plugins, the CLIs and the desktop app) and revokes the tokens on the server.

How the AI client itself authenticates depends on the config that was written:

Project key (default for Cloud HTTP when you are signed in). The config carries Authorization: Bearer agd_pk_…, a non-expiring, revocable key bound to this project only. Keys are kept in ~/.ai-game-dev/project-keys.json. Regenerate key in the window, or setup-mcp --regenerate-key, replaces it and revokes the old one.
OAuth (URL only). No credential in the file; the client opens a browser sign-in the first time it connects. You get this when you are not signed in, or with setup-mcp --oauth.
Personal Access Token. For CI or clients that cannot do a browser login, create a token in your ai-game.dev account (see Authentication) and pass it with setup-mcp --token <token>.

Treat project keys and tokens like passwords. Files such as .mcp.json live in your project folder, so check your .gitignore before committing them. Authentication explains the account side.

Supported AI agents

The window's AI agent dropdown lists these configurators. Configure writes the file shown; Remove takes the entry out again.

Agent	Config file written	CLI id
Claude Code	`.mcp.json` (project root)	`claude-code`
Claude Desktop	`claude_desktop_config.json` in Claude's app data folder	`claude-desktop`
Cursor	`.cursor/mcp.json`	`cursor`
Visual Studio Code (Copilot)	`.vscode/mcp.json`	`vscode-copilot`
Visual Studio (Copilot)	`.vs/mcp.json`	`vs-copilot`
Rider (Junie)	`.junie/mcp/mcp.json`	`rider-junie`
GitHub Copilot CLI	`~/.copilot/mcp-config.json`	`github-copilot-cli`
Gemini	`.gemini/settings.json`	`gemini`
Antigravity	`~/.gemini/config/mcp_config.json` and `~/.gemini/antigravity/mcp_config.json`	`antigravity`
Cline	`cline_mcp_settings.json` in VS Code's global storage	`cline`
Open Code	`opencode.json`	`open-code`
Codex	`.codex/config.toml`	`codex`
Kilo Code	`.kilocode/mcp.json`	window only
Zoo Code	`.roo/mcp.json`	window only
Unity AI	`UserSettings/mcp.json`	`unity-ai`
Other - Custom	shows the JSON to copy	`custom`

Relative paths are inside your Unity project. The server entry is always named ai-game-developer. Run unity-mcp-cli setup-mcp --list to see the ids your CLI version supports.

Configure with unity-mcp-cli

setup-mcp writes the same output as the window's Configure button, without opening Unity:

unity-mcp-cli setup-mcp claude-code ./MyUnityProject
unity-mcp-cli setup-mcp cursor ./MyUnityProject --transport stdio
unity-mcp-cli setup-mcp claude-code ./MyUnityProject --no-pin

The default transport is http. With --transport stdio the config launches the local server binary instead. All flags are in the CLI reference.

Configure by hand

Any MCP client that supports HTTP can use the hosted endpoint. Claude Code example:

claude mcp add --transport http ai-game-developer https://ai-game.dev/mcp

A generic mcpServers JSON config:

{
  "mcpServers": {
    "ai-game-developer": {
      "url": "https://ai-game.dev/mcp"
    }
  }
}

Replace the URL with your project's pinned URL (shown in the window's manual configuration steps) to target one project. The MCP endpoint page has snippets for every client, including VS Code's servers format and a PAT header.

Local server over HTTP

In Custom mode with the HTTP transport, point the client at the local server. The port is the one in the window's Server URL; the manual configuration steps shown for your agent in the window contain the exact URL, including the project pin:

{
  "mcpServers": {
    "ai-game-developer": {
      "url": "http://localhost:<port>"
    }
  }
}

Local server over stdio

With the stdio transport the client starts the server binary itself. On Windows:

claude mcp add ai-game-developer "<project>/Library/mcp-server/win-x64/gamedev-mcp-server.exe" port=<port> plugin-timeout=10000 client-transport=stdio

Use osx-arm64, osx-x64, linux-x64, linux-arm64, win-x86 or win-arm64 for other platforms (without .exe outside Windows). Replace <project> with the full project path and <port> with the port from the window. Only one agent can use a stdio server at a time, and the window's Start/Stop button is disabled because the agent owns the process. Prefer HTTP unless your client has no HTTP support.

After configuring

Restart the AI client, or reconnect its MCP server, so it reads the new config. Then follow Getting started to check the connection. If the client shows no tools, see Troubleshooting.

Two ways to connect#

Pinned URLs#

Signing in#

Supported AI agents#

Configure with unity-mcp-cli#

Configure by hand#

Local server over HTTP#

Local server over stdio#

After configuring#

Two ways to connect

Pinned URLs

Signing in

Supported AI agents

Configure with unity-mcp-cli

Configure by hand

Local server over HTTP

Local server over stdio

After configuring