Split a 3D model into parts

Send a 3D model and MCPBytes splits it into separate part meshes. Every part gets a convex collider, and manifest.json describes how the parts fit together: bounds, contacts, symmetry, and mass estimates.

Input formats

.glb .gltf .obj .ply .stl .off .blend

Part formats

GLB (default), OBJ or PLY

Detail

low, medium (default) or high

Outputs

Part meshes, convex colliders, segmented.glb, manifest.json, face_to_part.bin, and all of them as one .zip

Metadata

Bounds, contacts, symmetry, mass and inertia estimates

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.

# The model file is the request body
curl "https://api.mcpbytes.com/v1/tools/split_3d_model/jobs?filename=airplane.glb" \
  -H "Authorization: Bearer $MCPBYTES_API_KEY" \
  --data-binary @airplane.glb

{
  "id": "j_4f7k2m9x1q8w3e6r5t0y2u7i9o",
  "tool": "split_3d_model",
  "status": "queued",
  "input": {
    "name": "airplane.glb",
    "bytes": 2481152,
    "source": "body"
  },
  "options": {
    "detail": "medium",
    "min_part_faces": 0,
    "min_part_area": null,
    "format": "glb",
    "preprocess": "auto",
    "segmented": true,
    "density": null,
    "max_parts": 32
  },
  "error": null,
  "result": null,
  "compute_ms": null,
  "credits_charged": null,
  "created_at": "2026-09-19T12:00:00.000Z",
  "started_at": null,
  "finished_at": null,
  "outputs_expire_at": "2026-09-20T12:00:00.000Z"
}

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

{
  "id": "j_4f7k2m9x1q8w3e6r5t0y2u7i9o",
  "tool": "split_3d_model",
  "status": "succeeded",
  "result": {
    "files": [
      {
        "name": "airplane_parts.zip",
        "bytes": 1873410,
        "sha256": "…",
        "url": "https://api.mcpbytes.com/blob/dl/j_4f7k2m9x1q8w3e6r5t0y2u7i9o/airplane_parts.zip?t=…"
      },
      {
        "name": "collision/part_000.glb",
        "bytes": 4212,
        "sha256": "…",
        "url": "https://api.mcpbytes.com/blob/dl/j_4f7k2m9x1q8w3e6r5t0y2u7i9o/collision/part_000.glb?t=…"
      },
      {
        "name": "manifest.json",
        "bytes": 20931,
        "sha256": "…",
        "url": "https://api.mcpbytes.com/blob/dl/j_4f7k2m9x1q8w3e6r5t0y2u7i9o/manifest.json?t=…"
      },
      {
        "name": "meshes/part_000.glb",
        "bytes": 512604,
        "sha256": "…",
        "url": "https://api.mcpbytes.com/blob/dl/j_4f7k2m9x1q8w3e6r5t0y2u7i9o/meshes/part_000.glb?t=…"
      }
    ],
    "schema_version": 2,
    "part_count": 7,
    "input_faces": 48210,
    "exported_faces": 48210,
    "notes": [],
    "timings_s": {
      "total": 12.4
    }
  },
  "compute_ms": 14210,
  "credits_charged": 20,
  "finished_at": "2026-09-19T12:00:16.000Z",
  "outputs_expire_at": "2026-09-20T12:00:00.000Z"
}

A job can be canceled while it is queued: POST /v1/jobs/{id}/cancel.

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": "airplane.glb"}'

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

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

To retry safely, send an Idempotency-Key header (or idempotency_key in a JSON body): a repeated key returns the original job instead of starting a new one.

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.

Parts are numbered by decreasing surface area, so part_000 is the largest. With format set to obj or ply, meshes and colliders use that extension. All files share one coordinate system: place every part and collider at the model's root transform to rebuild it.

Result summary

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

• Start with the defaults. If the parts are too coarse, run again with detail high; if there are too many small parts, use detail low or raise min_part_area. Each run is charged again.
• Read manifest.json first. Part names carry no meaning, so find the part you need by its bounds and contacts.
• Download <model>_parts.zip for everything at once, or single files from result.files when only some parts are needed.
• Blender input is converted to glTF axes (+Y up, +Z forward); source_to_output_transform in manifest.json relates the parts to the original scene. Formats without known axes or units report those fields as null.
• A model over the face limit fails with limit_exceeded: reduce it with simplify_3d_model first.

Your agent calls split_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, 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/split_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 split_3d_model chair.glb --out parts/
python scripts/mcpbytes.py run split_3d_model chair.glb \
  -o detail=high --out parts/
python scripts/mcpbytes.py read j_... manifest.json

From 20 credits. The price follows the input's size and is charged once the input has been measured; starting a job needs at least the smallest price. 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.

• Inspect a 3D modelCheck counts, dimensions and topology before splitting. The same upload_id works for both while the upload lasts.inspect_3d_model
• Simplify a 3D modelBring a model under the face limit before splitting it.simplify_3d_model
• Create a 3D modelSplit a generated model: download its model.glb and upload it (this tool takes no job_file).create_3d_model