GUIDES / MCP INTEGRATION

Connect an MCP client to TO3D

Use the live v2 HTTP endpoint to discover TO3D tools from an MCP-capable client. This guide records the endpoint and read-only discovery evidence; it does not claim that every client has been tested or that MCP can rig a model automatically.

Open API and MCP docs Read the API workflow

Verified 27 September 2026

Connect to the live endpoint

Configure your client with https://mcp.to3d.app/v2/mcp. It is a remote HTTP MCP server. Clients that support OAuth can complete TO3D WorkOS AuthKit sign-in; no-auth tools can prepare or inspect a request but authenticated generation still requires an account.

Use the /v2/mcp path for the current 14-tool surface.
Request openid and email when the client asks for OAuth scopes.
Signing in authorizes the connection; it does not submit a generation task by itself.

{
  "mcpServers": {
    "to3d": {
      "url": "https://mcp.to3d.app/v2/mcp"
    }
  }
}

Run MCP discovery

A client begins with initialize, then asks for tools/list and resources/list. These are the calls used for the live gate and are safe discovery requests; this page does not invoke a generation tool.

initialize establishes protocol and server information.
tools/list returns names, schemas, and security schemes.
resources/list returns the widget resources advertised by the server.

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"your-client","version":"1.0"}}}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
{"jsonrpc":"2.0","id":3,"method":"resources/list","params":{}}

The live 14-tool surface

The current v2 response separates OAuth-protected account and task actions from no-auth preparation or diagnostic actions. Tool names and schemas are the source of truth for a client implementation.

OAuth means the client must present the connected account session.
No auth means the tool can be called without an account token; it does not imply free generation.
Read-only hints describe a tool annotation and do not replace the server's authorization checks.

curl -fsS https://mcp.to3d.app/v2/mcp -H 'content-type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

Tools returned by tools/list at the live gate
Tool	Access	Purpose
`get_3d_credits`	OAuth	Read available credits
`estimate_3d_generation`	OAuth	Estimate generation credits
`generate_3d`	OAuth	Generate from an image
`image-to-3d`	No auth	Open the image picker
`process_image_url_to_3d`	No auth	Preview an image URL
`prepare_3d_generation`	No auth	Prepare a selected image
`cancel_3d_generation`	No auth	Cancel an unsubmitted request
`generate_3d_authenticated`	OAuth	Start a prepared generation
`get_authenticated_generation`	OAuth	Check a generation
`create_3d_job_from_url`	OAuth	Resume a prepared job
`get_3d_job_status`	OAuth	Check a job
`get_3d_result`	OAuth	Get a job result
`get_3d_status`	OAuth	Check a task
`report_widget_diagnostic`	No auth	Record a widget diagnostic

Follow the task flow

A client can prepare an image, authenticate when the user chooses to generate, start or resume the job, and then read status and result. Keep the resumeKey, intentId, jobId, or taskId returned by each stage instead of inventing an identifier.

Read credits and estimate before asking for a paid generation.
Use get_3d_job_status or get_3d_status to observe a task, then get_3d_result when the server reports completion.
The current endpoint does not expose an MCP humanoid-rigging tool; use the REST Skin Tokens workflow for a separate rig task.

prepare -> authenticate -> generate_3d_authenticated -> get_3d_job_status -> get_3d_result

Client and capability boundaries

The Web studio and REST API have their own contracts. An MCP client should display the tools and schemas it actually discovers, and should not copy OAuth, automatic rigging, or compatibility claims from another route.

The older /mcp path is an existing-v1 compatibility route and is not evidence for this v2 tool list.
OAuth support is recorded for this live endpoint; individual client sign-in flows still need client-specific verification.
No generation request was made for this guide.

endpoint=https://mcp.to3d.app/v2/mcp
legacy=https://mcp.to3d.app/mcp