AI3D Studio

npx add-mcp 'https://ai3d.studio/mcp'

Claude (web e desktop)

1. Abra Personalizar → Conectores e escolha "+" → Adicionar conector personalizado.
2. Cole https://ai3d.studio/mcp e selecione Adicionar.
3. Selecione Conectar, faça login e aprove os escopos solicitados na tela de consentimento.

Nos planos Team e Enterprise, um proprietário adiciona o conector em Configurações da organização → Conectores; os membros então selecionam Conectar.

Claude Code

claude mcp add --transport http ai3d-studio https://ai3d.studio/mcp
# then run /mcp inside Claude Code to sign in

ChatGPT

1. Ative Configurações → Segurança e login → Modo desenvolvedor (web; planos Plus, Pro, Business, Enterprise e Edu).
2. Crie um aplicativo em modo desenvolvedor no menu Plugins com a URL https://ai3d.studio/mcp.
3. Escolha OAuth como autenticação e faça login quando solicitado.

O ChatGPT renomeia esses menus com frequência; o guia de modo desenvolvedor da OpenAI tem os nomes atuais.

Cursor

Adicione o servidor a ~/.cursor/mcp.json (todos os projetos) ou .cursor/mcp.json (um projeto).

{
  "mcpServers": {
    "ai3d-studio": {
      "url": "https://ai3d.studio/mcp"
    }
  }
}

O Cursor abre a página de login no primeiro uso. Para usar uma chave, adicione "headers": {"Authorization": "Bearer ${env:API_KEY}"}.

Ferramentas

Ferramenta	Escopo	O que faz
list_models	read	Modelos que você pode gerar: cenas (texto para 3D, imagem para 3D, …), créditos nas opções padrão e com include_inputs os campos de opções de cada cena. Também os predefinidos de imagem (figurino, estilo, pose, converter) e as cenas que ele processa em lote.
estimate_cost	read	Créditos que uma geração cobraria pelas opções fornecidas e se seu saldo cobre. Mesma validação e preço que generate_3d; nada é iniciado ou cobrado.
get_balance	read	Créditos que você pode gastar, nome do seu plano e — para uma chave de API com limite mensal — o que a chave usou e quando reinicia.
generate_3d	generate	Inicia uma geração 3D a partir de texto, imagem, várias vistas, esboço ou modelo (mode). Retorna um ID de trabalho imediatamente; passe idempotency_key em novas tentativas.
generate	generate	Inicia uma geração de qualquer tipo de mídia (mesmo corpo que POST /v1/generate, incluindo options.preset para um predefinido de imagem); passe idempotencyKey em novas tentativas.
get_job	read	Status, progresso, créditos cobrados e reembolsados, e os arquivos de resultado com URLs públicas de download, incluindo outros formatos quando o modelo os retornou.
list_job_files	read	Os formatos que um trabalho concluído já tem (o resultado principal e alternativas) com um link para cada um. Não converte entre formatos.
cancel_job	generate	Cancela um trabalho ainda em execução; créditos por saídas não concluídas são reembolsados. Seguro repetir.
start_batch	generate	Executa um modelo sobre várias imagens da Biblioteca (POST /v1/batches): uma execução cada, cobrada ao iniciar. A cotação deve caber no saldo e em qualquer limite mensal; passe idempotency_key em novas tentativas.
list_batches	read	Seus lotes de uma cena do último dia e quantas imagens seu plano permite por lote.
get_batch	read	Progresso de um lote: estado de cada imagem, o job_id da execução (para get_job), créditos e se pode ser repetido.
cancel_batch	generate	Cancela imagens de um lote que não começaram; elas nunca são cobradas. Seguro repetir.
retry_batch	generate	Coloca novamente na fila as imagens falhas de um lote como novas execuções, todas ou as item_ids fornecidas.
convert_model	generate	Converte, compacta ou redimensiona um GLB da Biblioteca para GLB, STL, 3MF, OBJ ou PLY no servidor (POST /v1/tools/convert), arquivado de volta na Biblioteca. Grátis; a mesma conversão retorna a mesma criação.

Todo resultado carrega structuredContent que corresponde ao outputSchema da ferramenta, além de uma cópia em texto que lista todos os links de download para clientes que não mostram conteúdo estruturado. Ferramentas que apenas leem são marcadas como somente leitura; cancel_job e cancel_batch são marcadas como destrutivas, então os clientes perguntam antes de executá-las. Uma execução típica é list_models, estimate_cost, generate_3d, depois get_job até is_terminal ser verdadeiro.

Em um cliente que renderiza MCP Apps (Claude, ChatGPT, Cursor, VS Code), generate_3d e get_job abrem um visualizador 3D interativo ao lado do resultado: orbitar, alternar entre texturizado, argila e wireframe, e baixar. O visualizador acompanha o trabalho sozinho com viewer_job_state, um auxiliar marcado como somente aplicativo para que o cliente o mantenha fora da lista de ferramentas do modelo. Um cliente sem MCP Apps recebe os mesmos fatos como texto, com todos os links de download.

Os nomes antigos list_capabilities (agora list_models), get_workflow (agora get_job), get_account (agora get_balance) ainda funcionam, mas não são listados.

Versões de protocolo, progresso e tarefas

O servidor fala 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26. 2026-07-28 é sem estado: não há handshake initialize nem sessão. Cada solicitação nomeia sua versão no cabeçalho MCP-Protocol-Version e em _meta, repete o método em Mcp-Method e o nome da ferramenta em Mcp-Name, e uma solicitação cujos cabeçalhos discordam do corpo é recusada com HTTP 400 e erro -32020. server/discover retorna as versões, capacidades e instruções. Clientes nas versões anteriores continuam usando initialize, sem alterações.

A geração leva mais tempo do que uma solicitação deveria esperar. Em generate_3d, generate e get_job, um cliente que envia _meta.progressToken e aceita text/event-stream recebe notifications/progress enquanto o trabalho executa, por até cerca de 24 segundos, e então o resultado normal. Fechar o stream interrompe a observação; nunca cancela o trabalho. Um cliente que declara a extensão io.modelcontextprotocol/tasks recebe um trabalho iniciado como tarefa: seu taskId é o ID do trabalho, lido com tasks/get e interrompido com tasks/cancel. Todo outro cliente continua consultando get_job.

Navegadores não podem chamar este endpoint de outro site: uma solicitação que carrega um cabeçalho Origin é recusada com HTTP 403 a menos que venha deste site, do próprio aplicativo web de um assistente ou de um endereço de loopback. Os próprios assistentes não enviam Origin.

Como funciona o login

1. Listar ferramentas não exige credencial; a primeira chamada de ferramenta responde HTTP 401 com WWW-Authenticate: Bearer resource_metadata=….
2. O cliente lê https://ai3d.studio/.well-known/oauth-protected-resource/mcp, cujo resource é exatamente https://ai3d.studio/mcp, e os metadados do servidor de autorização em https://ai3d.studio/api/auth.
3. O cliente se registra — Claude e ChatGPT com um documento de metadados de ID de cliente, outros com registro dinâmico de cliente — e inicia um fluxo de código de autorização com PKCE (S256).
4. Você faz login e aprova na tela de consentimento.
5. O token de acesso é vinculado a https://ai3d.studio/mcp (aud) com os escopos read e generate; ele é recusado pela API REST e vice-versa. Tokens de atualização giram no uso.
6. Um token sem um escopo recebe HTTP 403 insufficient_scope, e o cliente pode solicitá-lo.

A regra de plano da API REST se aplica aqui também (o acesso à API está incluído em todo plano pago e pacote de créditos), e chamadas de ferramenta cobram os créditos da conta conectada.