AI3D Studio

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

Claude (web and desktop)

1. Open Customize → Connectors and choose "+" → Add custom connector.
2. Paste https://ai3d.studio/mcp and select Add.
3. Select Connect, sign in, and approve the requested scopes on the consent screen.

On Team and Enterprise plans an owner adds the connector under Organization settings → Connectors; members then select Connect.

Claude Code

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

ChatGPT

1. Turn on Settings → Security and login → Developer mode (web; Plus, Pro, Business, Enterprise and Edu plans).
2. Create a developer-mode app from the Plugins menu with the URL https://ai3d.studio/mcp.
3. Choose OAuth as the authentication and sign in when prompted.

ChatGPT renames these menus often; the OpenAI developer-mode guide has the current names.

Cursor

Add the server to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project).

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

Cursor opens the sign-in page on first use. To use a key instead, add "headers": {"Authorization": "Bearer ${env:API_KEY}"}.

Tools

Tool	Scope	What it does
list_models	read	Models you can generate with: scenes (text-to-3d, image-to-3d, …), credits at default options, and with include_inputs each scene’s option fields. Also the image presets (figurine, style, pose, convert) and the scenes it batches.
estimate_cost	read	Credits a generation would charge for the options you give, and whether your balance covers it. Same validation and price as generate_3d; nothing is started or charged.
get_balance	read	Credits you can spend, your plan name, and — for an API key with a monthly limit — what the key has used and when it resets.
generate_3d	generate	Start a 3D generation from text, an image, several views, a sketch or a model (mode). Returns a job id at once; pass idempotency_key on retries.
generate	generate	Start a generation of any media type (same body as POST /v1/generate, including options.preset for an image preset); pass idempotencyKey on retries.
get_job	read	Status, progress, credits charged and refunded, and the result files with public download URLs, including other formats where the model returned them.
list_job_files	read	The formats a finished job already has (the main result and any alternates) with a link to each. It does not convert between formats.
cancel_job	generate	Cancel a job that is still running; credits for unfinished outputs are refunded. Safe to repeat.
start_batch	generate	Run one model over several Library pictures (POST /v1/batches): one run each, charged as it starts. The quote must fit the balance and any monthly limit; pass idempotency_key on retries.
list_batches	read	Your batches of a scene from the last day, and how many pictures your plan lets one batch hold.
get_batch	read	A batch’s progress: each picture’s state, the job_id of its run (for get_job), credits and whether it can be retried.
cancel_batch	generate	Cancel a batch’s pictures that have not started; they are never charged. Safe to repeat.
retry_batch	generate	Queue a batch’s failed pictures again as new runs, all of them or the item_ids given.
convert_model	generate	Convert, compress or resize a Library GLB to GLB, STL, 3MF, OBJ or PLY on the server (POST /v1/tools/convert), filed back in the Library. Free; the same conversion returns the same creation.

Every result carries structuredContent that matches the tool's outputSchema, plus a text copy that lists every download link for clients that do not show structured content. Tools that only read are marked read-only; cancel_job and cancel_batch are marked destructive, so clients ask before running them. A typical run is list_models, estimate_cost, generate_3d, then get_job until is_terminal is true.

In a client that renders MCP Apps (Claude, ChatGPT, Cursor, VS Code), generate_3d and get_job open an interactive 3D viewer next to the result: orbit, switch between textured, clay and wireframe, and download. The viewer follows the job on its own with viewer_job_state, a helper that is marked app-only so a client keeps it out of the model's tool list. A client without MCP Apps gets the same facts as text, with every download link.

The older names list_capabilities (now list_models), get_workflow (now get_job), get_account (now get_balance) still work but are not listed.

Protocol versions, progress and tasks

The server speaks 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26. 2026-07-28 is stateless: there is no initialize handshake and no session. Each request names its version in the MCP-Protocol-Version header and in _meta, repeats the method in Mcp-Method and the tool name in Mcp-Name, and a request whose headers disagree with its body is refused with HTTP 400 and error -32020. server/discover returns the versions, capabilities and instructions. Clients on the earlier versions keep using initialize, unchanged.

Generation takes longer than a request should wait. On generate_3d, generate and get_job, a client that sends _meta.progressToken and accepts text/event-stream receives notifications/progress while the job runs, for up to about 24 seconds, and then the normal result. Closing the stream stops the watching; it never cancels the job. A client that declares the io.modelcontextprotocol/tasks extension is handed a started job as a task instead: its taskId is the job id, read with tasks/get and stopped with tasks/cancel. Every other client keeps polling get_job.

Browsers cannot call this endpoint from another site: a request that carries an Origin header is refused with HTTP 403 unless it comes from this site, an assistant's own web app or a loopback address. Assistants themselves send no Origin.

How sign-in works

1. Listing tools needs no credential; the first tool call answers HTTP 401 with WWW-Authenticate: Bearer resource_metadata=….
2. The client reads https://ai3d.studio/.well-known/oauth-protected-resource/mcp, whose resource is exactly https://ai3d.studio/mcp, and the authorization server metadata under https://ai3d.studio/api/auth.
3. The client registers itself — Claude and ChatGPT with a client ID metadata document, others with dynamic client registration — and starts an authorization-code flow with PKCE (S256).
4. You sign in and approve on the consent screen.
5. The access token is bound to https://ai3d.studio/mcp (aud) with the scopes read and generate; it is refused by the REST API and vice versa. Refresh tokens rotate on use.
6. A token missing a scope gets HTTP 403 insufficient_scope, and the client can ask for it.

The REST API's plan rule applies here too (API access is included with every paid plan and credit pack), and tool calls bill the signed-in account's credits.