# Connecting AI clients

Connect Claude Code, Cursor, Copilot, Codex, Gemini and other MCP clients to Unity MCP through the ai-game.dev cloud endpoint or a local server.

_Last updated: 2026-11-04_

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](https://ai-game.dev/docs/wiki/unity/configuration#connection-modes) 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.

## Signing in

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](https://ai-game.dev/docs/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](https://ai-game.dev/docs/auth)) 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](https://ai-game.dev/docs/auth) 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.

**Tip**

Claude Desktop and Unity AI do not use generated skills, and the Custom entry lets you choose the skills folder. For the other agents, also turn on **Skills > Auto-generate** (or run `setup-skills`) so the agent learns RQL.

## Configure with unity-mcp-cli

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

```bash
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](https://ai-game.dev/docs/wiki/unity/cli#setup-mcp).

## Configure by hand

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

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

A generic `mcpServers` JSON config:

```json
{
  "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](https://ai-game.dev/mcp-endpoint-info) 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:

```json
{
  "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:

```bash
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](https://ai-game.dev/docs/wiki/unity/getting-started#verify) to check the connection. If the client shows no tools, see [Troubleshooting](https://ai-game.dev/docs/wiki/unity/troubleshooting#no-tools).

---

Source (HTML): https://ai-game.dev/docs/wiki/unity/connecting-ai-clients