# Connecting AI clients

Connect Claude Code, Cursor, Copilot, Codex, Gemini and other MCP clients to Unreal 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 your Unreal Editor, how sign-in works, and how to write the MCP config for each supported agent. If you only want the quickest path, the **Configure** button in the editor's **AI agent** section (see [Getting started](https://ai-game.dev/docs/wiki/unreal/getting-started#ai-client)) does all of this for you.

## Cloud or Custom: choose a connection mode

The **Connection** section of the AI Game Developer window has a **Custom / Cloud** switch. The same setting is `UNREAL_MCP_CONNECTION_MODE` (see [Configuration](https://ai-game.dev/docs/wiki/unreal/configuration)).

|  | Cloud (default) | Custom |
| --- | --- | --- |
| Server | The hosted endpoint at ai-game.dev | A `gamedev-mcp-server` you run, usually on `localhost` |
| Sign-in | Your ai-game.dev account, device-code flow | Optional: none, a shared token, or OAuth |
| What runs locally | The editor and its bridge | The editor, its bridge and the local server |
| Good for | Most users, several machines, working across firewalls | Fully local setups, offline work, CI |

## Cloud mode

In Cloud mode the bridge connects to ai-game.dev and your AI client connects to the same endpoint, `https://ai-game.dev/mcp`. The server routes the client's tool calls to your editor. See the [MCP endpoint page](https://ai-game.dev/mcp-endpoint-info) for the endpoint itself.

### Sign in with the device-code flow

You sign in once per machine. Any of these works, and they share one credential store (`~/.ai-game-dev/credentials.json`) with the app, the other engine plugins and the CLIs:

- In the editor: choose **Cloud**, click **Authorize**, open the verification page, enter the user code shown in the window and approve.
- In a terminal: `unreal-mcp-cli login`.
- In the AI Game Dev app: sign in as usual.

**Warning:** **Revoke** in the editor signs out the whole machine, not just this project. The editor asks for confirmation first, because every AI Game Dev tool that shares the credential (engine plugins, CLIs and the desktop app) is signed out.

How accounts, devices and tokens work is covered on the [authentication page](https://ai-game.dev/docs/auth).

### Project-pinned URLs

If your account has several editors connected, a client using the plain `https://ai-game.dev/mcp` URL may reach the wrong one. So the plugin and `unreal-mcp-cli setup-mcp` write a **project-pinned** URL by default:

```text
https://ai-game.dev/mcp/p/<pin>
```

The pin is derived from the project folder, so the client always routes to this project's editor. Use `setup-mcp --no-pin` to write the plain URL instead.

### Project keys

When the machine is signed in, a Cloud config also carries a **project key**, an `Authorization: Bearer agd_pk_…` header bound to this project. With it, the agent needs no sign-in of its own. The key does not expire, can be revoked, and is cached in `~/.ai-game-dev/project-keys.json` so every agent of the project reuses it.

- `setup-mcp --oauth` writes a URL-only config instead; the agent then runs its own OAuth sign-in.
- `setup-mcp --regenerate-key`, or the **Regenerate key** button in the editor's AI agent section, creates a new key, rewrites the configured agents with it and revokes the old one.
- An explicit `--token` wins over both.

If the machine is not signed in, the config is URL-only and the agent signs in itself.

## Custom mode: a local server

In Custom mode the bridge connects to a server you control, normally the shared `gamedev-mcp-server` running on your machine. Each project gets a fixed local port in the range 20000 to 29999, derived from the project path, so the editor and the CLI agree on it without any config.

To run it from the editor:

1. Switch the Connection section to **Custom**.
2. In the **MCP server** card, choose the **http** transport and click **Start**. The editor downloads the pinned server release if it is missing, starts it and stops it when the editor exits. The Start button works only with Custom mode and the http transport.
3. Choose an **Authorization** mode: **none** (local, anonymous), **token** (a shared secret; **New** generates one, hold **Reveal** to see it), or **oauth**.

To start it from a terminal instead, use `unreal-mcp-cli open ./YourProject --start-server --connection-mode Custom`, or set `UNREAL_MCP_START_SERVER=true` with `unreal-mcp-cli configure`.

**Note:** If you point a local server at the editor but the window still says Cloud, the bridge connects to ai-game.dev and your local server answers "No connected clients". Set Custom mode explicitly. Passing `--host` to `unreal-mcp-cli open` selects Custom automatically.

## Write the client config with setup-mcp

`unreal-mcp-cli setup-mcp <agent>` writes an MCP config entry for one agent. It reads the project's saved connection settings, so open the project in the editor once first (or pass `--url`).

```bash
# Claude Code: writes .mcp.json in the project
unreal-mcp-cli setup-mcp claude-code --path ./YourProject

# Cursor, with the local server over stdio instead of http
unreal-mcp-cli setup-mcp cursor --path ./YourProject --transport stdio

# Print the snippet without writing anything
unreal-mcp-cli setup-mcp vscode-copilot --path ./YourProject --dry-run

# List every agent and its config path
unreal-mcp-cli setup-mcp --list
```

With `--transport stdio` the CLI downloads the pinned `gamedev-mcp-server` release into `<project>/Intermediate/UnrealMCP/server/` and the agent starts that server itself.

### Supported agents

| Agent | `setup-mcp` id | Config file |
| --- | --- | --- |
| Claude Code | `claude-code` | `.mcp.json` (project) |
| Claude Desktop | `claude-desktop` | `claude_desktop_config.json` (user) |
| Cursor | `cursor` | `.cursor/mcp.json` (project) |
| Visual Studio Code (Copilot) | `vscode-copilot` | `.vscode/mcp.json` (project) |
| Visual Studio (Copilot) | `vs-copilot` | `.vs/mcp.json` (project) |
| Rider (Junie) | `rider-junie` | `.junie/mcp/mcp.json` (project) |
| GitHub Copilot CLI | `github-copilot-cli` | `~/.copilot/mcp-config.json` (user) |
| Gemini | `gemini` | `.gemini/settings.json` (project) |
| Antigravity | `antigravity` | `mcp_config.json` under `~/.gemini/` (user) |
| Cline | `cline` | `cline_mcp_settings.json` in VS Code's global storage (user) |
| Open Code | `open-code` | `opencode.json` (project) |
| Codex | `codex` | `.codex/config.toml` (project) |
| Kilo Code | `kilo-code` | `.kilocode/mcp.json` (project) |
| Any other MCP client | `custom` | `mcp.json` (project) |

The editor's **AI agent** dropdown offers the same kind of one-click setup, plus **Remove** to delete the entry, **Tutorial** and **Download / Docs** links, and **Generate skill files** for agents that support skills.

## Claude Code and Unreal Engine

Claude Code reads `.mcp.json` from the folder you start it in. So for Claude Code in Unreal:

1. Run `unreal-mcp-cli setup-mcp claude-code --path ./YourProject` (or **Configure** in the editor with Claude Code selected).
2. Start Claude Code from the project folder.
3. Ask it to "list the actors in the current level" to confirm the Unreal tools are available.

Optionally, `unreal-mcp-cli setup-skills --path ./YourProject` writes a Claude Code skill (`.claude/skills/unreal-mcp/SKILL.md`) that tells Claude how to drive this project's MCP server.

## Other clients

Ready-made config snippets for many clients, including ones not listed above, are on the [MCP endpoint page](https://ai-game.dev/mcp-endpoint-info). The [ecosystem overview](https://ai-game.dev/docs/ecosystem) shows how the server, plugins and app work together.

---

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