3D-Agent (external agents, Ultra)

Repasse tarefas de Blender para o 3D-Agent a partir do Claude Code, Claude Desktop, Cursor ou Codex. Um servidor MCP local (uma ferramenta, 3d_agent(task)) no aplicativo de desktop pago 3D-Agent para macOS e Windows, plano Ultra. Não é um servidor MCP do Blender.

Ver em 3d-agent.comExperimente este MCPPatrocinado

Documentação

Use 3D-Agent from Claude Code, Claude Desktop, Cursor or Codex

Para controlar o Blender a partir do Claude Code, Claude Desktop, Cursor ou Codex, conecte-o ao servidor MCP local que o 3D-Agent (3d-agent.com) executa enquanto o aplicativo de desktop está aberto. O aplicativo entrega uma tarefa ao 3D-Agent em linguagem natural, o 3D-Agent realiza o trabalho na sua cena do Blender aberta, e a resposta volta para o aplicativo.

Isso requer o plano Ultra. Cada tarefa usa um prompt, como uma mensagem que você digita.

Requisitos

  • O plano Ultra. Um bônus de primeiro mês em outro plano não conta.
  • O aplicativo de desktop do 3D-Agent, aberto e conectado, no macOS 12 ou posterior ou Windows 10 ou posterior.
  • Blender 4.2 ou posterior, aberto e conectado ao 3D-Agent.
  • Um destes aplicativos: Claude Code, Claude Desktop, Cursor, Codex, o aplicativo de desktop do ChatGPT (macOS 14 ou posterior) ou ComfyUI.

Configurar um aplicativo

1. Abra External agents

No 3D-Agent, abra Settings → External agents.

2. Ative Allow connections

Isso cria o token de conexão que os aplicativos usam para acessar o 3D-Agent.

3. Clique em Set up

Clique em Set up ao lado do aplicativo e siga a mensagem de status.

O Set up escreve a configuração de cada aplicativo para você, então você nunca precisa digitar uma porta ou token. As seções abaixo mostram o que ele escreve, caso você queira verificar ou fazer manualmente.

AplicativoO que o Set up fazQuando está pronto
Claude CodeAdiciona o 3D-Agent com claude mcp addSua próxima sessão do Claude Code
Claude DesktopAbre uma extensão do 3D-Agent (.mcpb)Assim que você instalá-la no Claude Desktop
CursorAbre um link de instalação do CursorAssim que você aprovar o servidor no Cursor
Codex e o aplicativo ChatGPTAdiciona o 3D-Agent ao seu config.toml do CodexNa próxima execução do Codex. Reinicie o aplicativo ChatGPT se estiver aberto.
ComfyUIInstala um nó do 3D-AgentAssim que você reiniciar o ComfyUI e adicionar o nó a um fluxo de trabalho

Para desfazer a configuração de um aplicativo, clique em Remove.

Encontre sua porta e token

Você só precisa deles para uma configuração manual. Em Settings → External agents, abra Advanced:

  • Connection token: clique no ícone de olho para exibi-lo, ou no ícone de copiar para copiá-lo.
  • Set up any other client: a configuração do servidor, com sua porta na URL.

O 3D-Agent usa a porta 1337 quando ela está livre, e outra porta quando não está. Sempre copie a porta do painel. Nos exemplos abaixo, substitua <port> e <token> pelos seus.

Claude Code

O Set up remove qualquer entrada antiga de 3d-agent e depois executa:

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

O --scope user torna o 3D-Agent disponível em todos os seus projetos. O Claude Code conecta-se aos servidores MCP quando uma sessão inicia, então inicie uma nova sessão após a configuração. Para verificar se o 3d-agent está conectado, execute /mcp no Claude Code ou claude mcp list em um terminal.

Se a configuração falhar, clique em Copy command e execute você mesmo. O comando copiado não tem a flag --scope, então ele adiciona o 3D-Agent apenas ao projeto atual. Execute-o na pasta do seu projeto, ou adicione --scope user.

Depois, peça ao Claude Code para trabalhos 3D:

Use 3D-Agent to model a low-poly wooden crate in Blender, then tell me its dimensions.

Claude Desktop

O Claude Desktop conecta-se por meio de uma extensão do 3D-Agent. O Set up escreve o arquivo da extensão e o abre. Instale-o quando o Claude Desktop pedir, e ele se conectará sozinho.

O arquivo está em:

  • macOS: ~/Library/Application Support/com.3d-agent.app/claude-desktop/3d-agent.mcpb
  • Windows: %APPDATA%\com.3d-agent.app\claude-desktop\3d-agent.mcpb

Para instalá-lo manualmente, no Claude Desktop abra Settings → Extensions → Advanced settings → Install Extension… e escolha esse arquivo.

A extensão carrega sua porta e token e executa um pequeno relay no Node.js integrado do Claude Desktop. Nenhuma destas alternativas funciona:

  • claude_desktop_config.json só inicia servidores locais de linha de comando (stdio), não servidores HTTP como o do 3D-Agent.
  • Conectores personalizados em Settings → Connectors conectam-se pela nuvem da Anthropic, então não conseguem acessar 127.0.0.1 no seu computador.

Cursor

O Set up abre um link de instalação do Cursor. Aprove o servidor quando o Cursor pedir.

Para adicioná-lo manualmente, coloque isto em ~/.cursor/mcp.json para todos os projetos, ou .cursor/mcp.json para um projeto:

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

Se o Cursor não conseguir conectar, abra o painel Output e escolha MCP Logs.

Codex e o aplicativo ChatGPT

O Set up adiciona isto ao seu arquivo de configuração do Codex:

[mcp_servers."3d-agent"]
url = "http://127.0.0.1:<port>/mcp"
http_headers = { Authorization = "Bearer <token>" }
tool_timeout_sec = 960

O Codex interrompe uma chamada de ferramenta após 60 segundos por padrão, e tarefas do 3D-Agent podem levar até 15 minutos. Se a linha tool_timeout_sec = 960 estiver faltando, adicione-a.

O arquivo é ~/.codex/config.toml no macOS e %USERPROFILE%\.codex\config.toml no Windows, ou config.toml na sua pasta CODEX_HOME se você definiu uma.

O Codex CLI, a extensão IDE do Codex e o aplicativo de desktop do ChatGPT compartilham este arquivo, então uma configuração cobre os três. O CLI o reconhece na próxima execução. Se o aplicativo ChatGPT estiver aberto, feche e reabra. Para verificar, execute codex mcp list, ou /mcp no Codex.

Se a configuração falhar, clique em Copy config e cole o bloco no arquivo você mesmo. Não use codex mcp add: ele só lê um token de uma variável de ambiente (--bearer-token-env-var), não de um cabeçalho.

ComfyUI

O ComfyUI não tem suporte a MCP, então o Set up instala um nó ComfyUI-3D-Agent na pasta custom_nodes do ComfyUI. Reinicie o ComfyUI e adicione o nó 3D-Agent a um fluxo de trabalho.

Se o 3D-Agent não encontrar o ComfyUI, clique em Choose folder e escolha a pasta do ComfyUI. Ela deve conter main.py e uma pasta custom_nodes.

A fila do ComfyUI espera enquanto o nó executa sua tarefa. Cancelar no ComfyUI interrompe a espera, mas a tarefa continua rodando no 3D-Agent.

Qualquer outro cliente MCP

Qualquer cliente que suporte Streamable HTTP com cabeçalhos pode conectar. Copie a configuração de Set up any other client em Advanced. É o mesmo JSON do exemplo do Cursor. Clientes que só suportam servidores stdio ou SSE não conseguem conectar.

O que acontece quando um aplicativo chama o 3D-Agent?

  1. O aplicativo vê uma ferramenta, 3d_agent, com um campo obrigatório, task: o que você quer que seja feito e como você vai avaliar, em linguagem natural.
  2. O 3D-Agent executa a tarefa como um prompt que você digita. Ele lê sua cena, usa suas ferramentas do Blender e faz checkpoints antes de edições arriscadas.
  3. Quando o turno termina, o 3D-Agent envia sua resposta final de volta ao aplicativo como texto, e o modelo do aplicativo continua.

A chamada permanece aberta até o turno terminar, por até 15 minutos. Mantenha o 3D-Agent aberto até a resposta chegar.

O outro aplicativo nunca controla o Blender diretamente. Ele entrega a tarefa, e o 3D-Agent escolhe as ferramentas do Blender.

Quanto custa?

Cada tarefa usa um dos 800 prompts mensais do seu plano Ultra. Tarefas recusadas porque você não está no Ultra não usam um prompt. Veja Plans and limits.

O 3D-Agent é um servidor MCP do Blender?

Não. Um servidor MCP do Blender dá a um assistente comandos de baixo nível do Blender, e o assistente faz o trabalho 3D. O 3D-Agent é seu próprio agente para o Blender, com suas próprias ferramentas, checkpoints e limites de etapas. Seu servidor MCP expõe uma ferramenta que entrega uma tarefa inteira a esse agente.

Você não precisa de um add-on MCP do Blender. Se você tiver um para outra ferramenta, desative-o enquanto usa o 3D-Agent.

Para aprender como o protocolo funciona, veja What is Blender MCP?. Para comparar as opções de MCP do Blender, veja Blender MCP.

Ler o status de um aplicativo

StatusSignificado
Not set upVocê ainda não configurou este aplicativo.
ReadyConfigurado, mas o aplicativo ainda não enviou uma tarefa.
WorkingO aplicativo alcançou o 3D-Agent pelo menos uma vez. A linha mostra quando a última tarefa rodou e quantos turnos usou hoje, se mais de um.
Setup did not go throughClique em Retry. Para Claude Code e Codex, você também pode clicar em Copy command ou Copy config e adicionar você mesmo.

Working significa que a configuração funcionou antes, não que o aplicativo está conectado agora.

Limites

  • O 3D-Agent só aceita tarefas enquanto está aberto.
  • Ele executa uma tarefa por vez.
  • Um aplicativo ainda não pode continuar um chat específico do 3D-Agent.
  • Abaixo do Ultra, o painel mostra "Paused. Your apps stay set up, and tasks resume on Ultra." Tarefas são recusadas e não usam um prompt.
  • Desativar Allow connections desconecta todos os aplicativos e esquece suas configurações.
  • Remove all em Advanced desconecta todos os aplicativos e substitui o token. Configure cada aplicativo novamente depois.

Aviso: Qualquer pessoa com seu token de conexão pode gastar seus prompts. Mantenha-o privado.

Solução de problemas

O que você vêO que fazer
"3D-Agent: external agents need the Ultra plan."Atualize para o Ultra. Um bônus de primeiro mês não conta.
"3D-Agent: not signed in, or the token is wrong."Entre no 3D-Agent. Se você clicou em Remove all ou desativou e reativou Allow connections, o token antigo não funciona mais. Clique em Set up para o aplicativo novamente.
"3D-Agent: the app is not open."Abra o 3D-Agent e mantenha-o aberto até a tarefa terminar.
"3D-Agent: already working on a turn. Retry shortly."O 3D-Agent executa uma tarefa por vez. Tente novamente quando a atual terminar.
"3D-Agent: out of turns on this plan."Você usou os prompts deste mês. Veja Plans and limits.
"3D-Agent: continuing a specific thread is not supported yet."O aplicativo enviou um threadId. Peça para ele chamar 3d_agent com apenas um task.
Toda chamada falha, ou outro programa respondeOutro programa, como Razer Chroma, usa a porta 1337. Copie a porta do painel, ou clique em Set up novamente para o aplicativo receber a porta atual.
O aplicativo lista a ferramenta 3d_agent mas nunca a chamaNomeie a ferramenta no seu pedido, por exemplo Use the 3d_agent tool to….
O painel diz The local port is unavailableReinicie o 3D-Agent e verifique se outro programa usa a porta 1337.

Verifique o servidor manualmente

Envie uma solicitação MCP initialize com sua porta e 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"}}}'

Um servidor funcionando responde HTTP 200 com um cabeçalho mcp-session-id. Isso não inicia uma tarefa nem usa um prompt.

Próximos passos

  • Plans and limits: Compare planos por prompts, etapas e subagentes.
  • Connect to Blender: Veja como o 3D-Agent encontra o Blender e conecta-se a ele.
  • Settings: Encontre o que há em cada página de configurações.