3D-Agent (external agents, Ultra)

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) 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 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.
• 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 <port> and <token> with yours.

Claude Code

Set up removes any old 3d-agent entry, then runs:

claude mcp add --scope user --transport http 3d-agent http://127.0.0.1:<port>/mcp --header "Authorization: Bearer <token>"

--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:

{
  "mcpServers": {
    "3d-agent": {
      "url": "http://127.0.0.1:<port>/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

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:

[mcp_servers."3d-agent"]
url = "http://127.0.0.1:<port>/mcp"
http_headers = { Authorization = "Bearer <token>" }
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 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.

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?. To compare the Blender MCP options, see 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.
"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:

curl -i -X POST "http://127.0.0.1:<port>/mcp" \
  -H "Authorization: Bearer <token>" \
  -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: Compare plans by prompts, steps and subagents.
• Connect to Blender: See how 3D-Agent finds Blender and connects to it.
• Settings: Find what's on each settings page.