# Use 3D-Agent from Claude Code, Claude Desktop, Cursor or Codex To control Blender from Claude Code, Claude Desktop, Cursor or Codex, connect it to the local MCP server that 3D-Agent ([3d-agent.com](https://3d-agent.com)) runs while its desktop app is open. The app hands 3D-Agent a task in plain language, 3D-Agent does the work in your open Blender scene, and the reply goes back to the app. This needs the Ultra plan. Each task uses one prompt, like a message you type. ## Requirements - The **Ultra** plan. A [first-month boost](https://3d-agent.com/docs/plans-and-limits#first-month-boost) on another plan doesn't count. - The 3D-Agent desktop app, open and signed in, on macOS 12 or later or Windows 10 or later. - Blender 4.2 or later, open and [connected to 3D-Agent](https://3d-agent.com/docs/connect-blender). - One of these apps: Claude Code, Claude Desktop, Cursor, Codex, the ChatGPT desktop app (macOS 14 or later) or ComfyUI. ## Set up an app ### 1. Open External agents In 3D-Agent, open **Settings** → **External agents**. ### 2. Turn on Allow connections This creates the connection token that apps use to reach 3D-Agent. ### 3. Click Set up Click **Set up** next to the app, then follow its status message. **Set up** writes each app's configuration for you, so you never type a port or token. The sections below show what it writes, in case you want to check it or do it by hand. | App | What **Set up** does | When it's ready | | --- | --- | --- | | **Claude Code** | Adds 3D-Agent with `claude mcp add` | Your next Claude Code session | | **Claude Desktop** | Opens a 3D-Agent extension (`.mcpb`) | Once you install it in Claude Desktop | | **Cursor** | Opens a Cursor install link | Once you approve the server in Cursor | | **Codex and the ChatGPT app** | Adds 3D-Agent to your Codex `config.toml` | Codex's next run. Restart the ChatGPT app if it's open. | | **ComfyUI** | Installs a 3D-Agent node | Once you restart ComfyUI and add the node to a workflow | To undo an app's setup, click **Remove**. ### Find your port and token You only need these for a manual setup. In **Settings** → **External agents**, open **Advanced**: - **Connection token:** click the eye icon to show it, or the copy icon to copy it. - **Set up any other client:** the server config, with your port in the URL. 3D-Agent uses port `1337` when it's free, and another port when it isn't. Always copy the port from the panel. In the examples below, replace `` and `` with yours. ## Claude Code **Set up** removes any old `3d-agent` entry, then runs: ```bash claude mcp add --scope user --transport http 3d-agent http://127.0.0.1:/mcp --header "Authorization: Bearer " ``` `--scope user` makes 3D-Agent available in all your projects. Claude Code connects to MCP servers when a session starts, so start a new session after setup. To check that `3d-agent` is connected, run `/mcp` in Claude Code or `claude mcp list` in a terminal. If setup fails, click **Copy command** and run it yourself. The copied command has no `--scope` flag, so it adds 3D-Agent to the current project only. Run it in your project folder, or add `--scope user`. Then ask Claude Code for 3D work: > Use 3D-Agent to model a low-poly wooden crate in Blender, then tell me its dimensions. ## Claude Desktop Claude Desktop connects through a 3D-Agent extension. **Set up** writes the extension file and opens it. Install it when Claude Desktop asks, and it connects on its own. The file is at: - **macOS:** `~/Library/Application Support/com.3d-agent.app/claude-desktop/3d-agent.mcpb` - **Windows:** `%APPDATA%\com.3d-agent.app\claude-desktop\3d-agent.mcpb` To install it by hand, in Claude Desktop open **Settings** → **Extensions** → **Advanced settings** → **Install Extension…** and pick that file. The extension carries your port and token and runs a small relay on Claude Desktop's built-in Node.js. Neither of these works instead: - `claude_desktop_config.json` only starts local command-line (stdio) servers, not HTTP servers like 3D-Agent's. - Custom connectors under **Settings** → **Connectors** connect from Anthropic's cloud, so they can't reach `127.0.0.1` on your computer. ## Cursor **Set up** opens a Cursor install link. Approve the server when Cursor asks. To add it by hand, put this in `~/.cursor/mcp.json` for all projects, or `.cursor/mcp.json` for one project: ```json { "mcpServers": { "3d-agent": { "url": "http://127.0.0.1:/mcp", "headers": { "Authorization": "Bearer " } } } } ``` If Cursor can't connect, open its **Output** panel and pick **MCP Logs**. ## Codex and the ChatGPT app **Set up** adds this to your Codex config file: ```toml [mcp_servers."3d-agent"] url = "http://127.0.0.1:/mcp" http_headers = { Authorization = "Bearer " } tool_timeout_sec = 960 ``` Codex stops a tool call after 60 seconds by default, and 3D-Agent tasks can take up to 15 minutes. If the `tool_timeout_sec = 960` line is missing, add it. The file is `~/.codex/config.toml` on macOS and `%USERPROFILE%\.codex\config.toml` on Windows, or `config.toml` in your `CODEX_HOME` folder if you set one. The Codex CLI, the Codex IDE extension and the ChatGPT desktop app share this file, so one setup covers all three. The CLI picks it up on its next run. If the ChatGPT app is open, quit and reopen it. To check, run `codex mcp list`, or `/mcp` in Codex. If setup fails, click **Copy config** and paste the block into the file yourself. Don't use `codex mcp add`: it only reads a token from an environment variable (`--bearer-token-env-var`), not a header. ## ComfyUI ComfyUI has no MCP support, so **Set up** installs a `ComfyUI-3D-Agent` node in ComfyUI's `custom_nodes` folder. Restart ComfyUI, then add the **3D-Agent** node to a workflow. If 3D-Agent can't find ComfyUI, click **Choose folder** and pick the ComfyUI folder. It must contain `main.py` and a `custom_nodes` folder. The ComfyUI queue waits while the node runs its task. Canceling in ComfyUI stops the wait, but the task keeps running in 3D-Agent. ## Any other MCP client Any client that supports Streamable HTTP with headers can connect. Copy the config from **Set up any other client** under **Advanced**. It's the same JSON as the [Cursor](#cursor) example. Clients that only support stdio or SSE servers can't connect. ## What happens when an app calls 3D-Agent? 1. The app sees one tool, `3d_agent`, with one required field, `task`: what you want done and how you'll judge it, in plain language. 2. 3D-Agent runs the task like a prompt you type. It reads your scene, uses its Blender tools and makes checkpoints before risky edits. 3. When the turn ends, 3D-Agent sends its final reply back to the app as text, and the app's model carries on. The call stays open until the turn finishes, for up to 15 minutes. Keep 3D-Agent open until the reply arrives. The other app never controls Blender directly. It hands over the task, and 3D-Agent picks the Blender tools. ## What does it cost? Each task uses one of your Ultra plan's 800 prompts a month. Tasks refused because you're not on Ultra don't use a prompt. See [Plans and limits](https://3d-agent.com/docs/plans-and-limits). ## Is 3D-Agent a Blender MCP server? No. A Blender MCP server gives an assistant low-level Blender commands, and the assistant does the 3D work. 3D-Agent is its own agent for Blender, with its own tools, checkpoints and step limits. Its MCP server exposes one tool that hands a whole task to that agent. You don't need a Blender MCP add-on. If you have one for another tool, disable it while you use 3D-Agent. To learn how the protocol works, see [What is Blender MCP?](https://3d-agent.com/blender-mcp/what-is-mcp). To compare the Blender MCP options, see [Blender MCP](https://3d-agent.com/blender-mcp). ## Read an app's status | Status | Meaning | | --- | --- | | **Not set up** | You haven't set up this app yet. | | **Ready** | Set up, but the app hasn't sent a task yet. | | **Working** | The app has reached 3D-Agent at least once. The row shows when the last task ran, and how many turns it used today if more than one. | | **Setup did not go through** | Click **Retry**. For Claude Code and Codex, you can also click **Copy command** or **Copy config** and add it yourself. | **Working** means setup has worked before, not that the app is connected right now. ## Limits - 3D-Agent only takes tasks while it's open. - It runs one task at a time. - An app can't continue a specific 3D-Agent chat yet. - Below Ultra, the panel shows "Paused. Your apps stay set up, and tasks resume on Ultra." Tasks are refused and don't use a prompt. - Turning off **Allow connections** disconnects every app and forgets their setup. - **Remove all** under **Advanced** disconnects every app and replaces the token. Set up each app again afterwards. > **Warning:** Anyone with your connection token can spend your prompts. Keep it private. ## Troubleshooting | What you see | What to do | | --- | --- | | "3D-Agent: external agents need the Ultra plan." | Upgrade to Ultra. A first-month boost doesn't count. | | "3D-Agent: not signed in, or the token is wrong." | Sign in to 3D-Agent. If you clicked **Remove all** or turned **Allow connections** off and on, the old token no longer works. Click **Set up** for the app again. | | "3D-Agent: the app is not open." | Open 3D-Agent and keep it open until the task finishes. | | "3D-Agent: already working on a turn. Retry shortly." | 3D-Agent runs one task at a time. Try again when the current one finishes. | | "3D-Agent: out of turns on this plan." | You've used this month's prompts. See [Plans and limits](https://3d-agent.com/docs/plans-and-limits). | | "3D-Agent: continuing a specific thread is not supported yet." | The app sent a `threadId`. Ask it to call `3d_agent` with only a `task`. | | Every call fails, or another program answers | Another program, such as Razer Chroma, uses port `1337`. Copy the port from the panel, or click **Set up** again so the app gets the current port. | | The app lists the `3d_agent` tool but never calls it | Name the tool in your request, for example *Use the 3d_agent tool to…*. | | The panel says **The local port is unavailable** | Restart 3D-Agent, and check whether another program uses port `1337`. | ### Check the server by hand Send an MCP `initialize` request with your port and token: ```bash curl -i -X POST "http://127.0.0.1:/mcp" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"manual-curl","version":"1.0.0"}}}' ``` A working server answers `HTTP 200` with an `mcp-session-id` header. This doesn't start a task or use a prompt. ## Next steps - [Plans and limits](https://3d-agent.com/docs/plans-and-limits): Compare plans by prompts, steps and subagents. - [Connect to Blender](https://3d-agent.com/docs/connect-blender): See how 3D-Agent finds Blender and connects to it. - [Settings](https://3d-agent.com/docs/settings): Find what's on each settings page.