Rig a 3D model

Send one static GLB (a character, animal or creature) and get it back with a skeleton and skin weights, in the input's coordinates, scale and textures. Bones are named bone_0, bone_1, … with no body-part names, and no animation is added. Every job checks the rig: the skeleton's structure, weights that reach far from their bone, and a 45° bend of every bone that measures folded triangles, stretch and volume change. rig_report.json gives the status (passed, needs_review or failed_checks) and each issue with its bone, value and threshold; rig_preview.png shows the skeleton, the weights and the worst bend. A succeeded job means a valid rig was produced, not that it is ready to animate. Start the job, keep its id and poll: it takes a few minutes.

Formats

.glb (self-contained, uncompressed, one material, not already rigged or animated)

Outputs

model.glb (skinned, up to 4 bones per vertex), rig.json, rig_report.json, rig_preview.png and generation.json

Checks

Skeleton structure, far-reaching weights and a 45° bend test of every bone (folded triangles, stretch, volume)

Duration

Asynchronous; one-hour deadline including queueing and execution

Send the file as the request body with the options in the query string, or refer to it in a JSON body (upload_id or url) with an options object. The response is the new job; poll it until its status is final, then download the files in result.files.

# Idempotency-Key is required: repeating it returns the same job
curl "https://api.mcpbytes.com/v1/tools/rig_3d_model/jobs?filename=model.glb&seed=42" \
  -H "Authorization: Bearer $MCPBYTES_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  -H "Idempotency-Key: rig-example-001" \
  --data-binary @model.glb

{
  "tool": "rig_3d_model",
  "status": "queued",
  "input_kind": "file",
  "workflow": {
    "stage": "Rigging",
    "deadline": "2026-09-27T09:38:40.512Z",
    "cancel_pending": false,
    "refund_pending": false
  },
  "capabilities": {
    "can_cancel": true
  },
  "options": {
    "seed": 42
  },
  "result": null
}

# JOB_ID is the id from the create response; poll until status is final
curl "https://api.mcpbytes.com/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $MCPBYTES_API_KEY"

# Once status is succeeded, download each file from result.files[].url
curl -fsSLo model.glb "$MODEL_URL"

{
  "tool": "rig_3d_model",
  "status": "succeeded",
  "result": {
    "notes": [],
    "bone_count": 34,
    "status": "passed",
    "issues": [],
    "files": [
      {
        "name": "model.glb",
        "bytes": 14968112,
        "content_type": "model/gltf-binary",
        "url": "https://api.mcpbytes.com/blob/dl/…"
      },
      {
        "name": "rig.json",
        "bytes": 6549,
        "content_type": "application/json",
        "url": "https://api.mcpbytes.com/blob/dl/…"
      },
      {
        "name": "rig_report.json",
        "bytes": 5224,
        "content_type": "application/json",
        "url": "https://api.mcpbytes.com/blob/dl/…"
      },
      {
        "name": "rig_preview.png",
        "bytes": 215861,
        "content_type": "image/png",
        "url": "https://api.mcpbytes.com/blob/dl/…"
      },
      {
        "name": "generation.json",
        "bytes": 2241,
        "content_type": "application/json",
        "url": "https://api.mcpbytes.com/blob/dl/…"
      }
    ]
  },
  "compute_ms": 37404,
  "credits_charged": 20
}

Jobs of this tool take minutes. While one runs, workflow.stage says what is happening and workflow.deadline when it must finish. Cancel it with POST /v1/jobs/{id}/cancel while capabilities.can_cancel is true.

More on statuses, downloads and retention in Jobs & files.

One file per job, in one of these ways. The formats it accepts are listed in the overview.

# 1. Create an upload URL (valid for one hour)
curl https://api.mcpbytes.com/v1/uploads \
  -H "Authorization: Bearer $MCPBYTES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "model.glb"}'

# 2. PUT the file to the "url" from the response
curl -X PUT --data-binary @model.glb "$UPLOAD_URL"

# 3. Start the job with the "upload_id"
curl https://api.mcpbytes.com/v1/tools/rig_3d_model/jobs \
  -H "Authorization: Bearer $MCPBYTES_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"upload_id\": \"$UPLOAD_ID\",
    \"options\": {
      \"seed\": 42
    },
    \"idempotency_key\": \"rig_3d_model-upload-001\"
  }"

Put options in the query string when the file is the request body, in the options object of a JSON body, or pass them as arguments of the MCP tool. Leave an option out to use its default.

A succeeded job lists its files in result.files, each with a download url.

Download links last up to 24 hours, capped by output retention; read the job again for fresh links. A succeeded job means a valid rig was produced; whether it is good enough is in rig_report.json and rig_preview.png.

Result summary

Next to files, the job's result has a summary you can check without downloading anything:

• Read rig_report.json before using the rig, and look at rig_preview.png: needs_review means a measurement crossed its threshold; failed_checks means one reached twice its threshold, or a bone has no length.
• A rig that fails its checks can be tried again with another seed; each job is charged.
• Pass model.glb of a create_3d_model, create_3d_model_from_image or optimize_3d_model job as job_file, with no download in between.
• rig.json lists each bone's parent, rest position, side of the model (+x, -x or center) and how many vertices it moves: enough to pick bones without opening the GLB.
• Export one static mesh with one material. Models that are already skinned or animated, morph targets, several materials and vertex colours without a texture are refused before any charge.
• The rigged file grows with the triangle count; above 1,000,000 triangles the job is refused. Reduce the model with simplify_3d_model first.

Your agent calls rig_3d_model. Connect it to https://api.mcpbytes.com/mcp/3d for this tool and the rest of its family (Create a 3D model, Create a 3D model from an image, Optimize a 3D model, Simplify a 3D model, Animate a 3D model, Split a 3D model into parts, Inspect a 3D model), or to https://api.mcpbytes.com/mcp for every tool.

claude mcp add --transport http mcpbytes \
  https://api.mcpbytes.com/mcp/3d

codex mcp add mcpbytes --url https://api.mcpbytes.com/mcp/3d \
  --bearer-token-env-var MCPBYTES_API_KEY

{
  "mcpServers": {
    "mcpbytes": {
      "url": "https://api.mcpbytes.com/mcp/3d",
      "headers": {
        "Authorization": "Bearer ${env:MCPBYTES_API_KEY}"
      }
    }
  }
}

Arguments

The tool's options are flat arguments. Besides them:

What the agent sees

Setup for every client, and how agents upload files and read results: Connect over MCP.

The MCPBytes skill teaches agents this tool, in references/rig_3d_model.md. Agents without MCP run it through the REST API with the skill's script, which reads your key from MCPBYTES_API_KEY:

python scripts/mcpbytes.py run rig_3d_model model.glb \
  -o seed=42 --out rigged/
# Or an earlier job's output, without downloading it
python scripts/mcpbytes.py run rig_3d_model \
  --job-file j_... model.glb --no-wait
python scripts/mcpbytes.py job j_...

20 credits per job. The price is charged before paid processing starts, and a canceled job is refunded. A job that fails costs nothing: its charge is refunded.

One credit balance pays for every tool, and a new account starts with free credits. See Credits & prices or buy credits.

GET /v1/me returns your limits and current usage; Limits & errors explains what happens when one is reached.

A failed job comes back with error.code, error.message and often error.hint. Codes are stable. Inputs that fail with a validation error will fail again unchanged.

Requests can also fail before a job starts, with an HTTP status: see HTTP errors.

• Create a 3D modelIts model.glb goes straight in as job_file.create_3d_model
• Create a 3D model from an imageIts model.glb goes straight in as job_file.create_3d_model_from_image
• Simplify a 3D modelBrings a model under 1,000,000 triangles and makes the rigged file smaller: download its model.glb and upload it.simplify_3d_model
• Optimize a 3D modelIts model.glb goes straight in as job_file, at the triangle count you chose.optimize_3d_model
• Animate a 3D modelMake the rigged model move from a description: pass its model.glb as job_file.animate_3d_model