Simplify a 3D model

Simplification collapses edges while weighing normals, texture coordinates and vertex colours, so materials and textures pass through untouched and stay aligned. Ask for a triangle count or a ratio, optionally cap the deviation, and read the achieved count and error in simplify.json. A million-triangle generated model becomes a quarter of its size in seconds, ready for web viewers, engines and AR.

Formats

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

Outputs

model.glb, simplify.json and, on request, model.web.glb (Draco + WebP)

Textures

Materials and images unchanged; UVs, normals and vertex colours carried through

Targets

target_faces or ratio; optional max_error as a fraction of the model's extent

Aggressive mode

Continues across texture seams and topology when the target matters more than fidelity

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.

curl "https://api.mcpbytes.com/v1/tools/simplify_3d_model/jobs?filename=model.glb&target_faces=250000&web_copy=true" \
  -H "Authorization: Bearer $MCPBYTES_API_KEY" \
  --data-binary @model.glb

{
  "tool": "simplify_3d_model",
  "status": "queued",
  "options": {
    "target_faces": 250000,
    "aggressive": false,
    "lock_borders": true,
    "remove_debris": false,
    "web_copy": true
  },
  "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 the model from result.files[].url
curl -fsSLo model.glb "$MODEL_URL"

{
  "tool": "simplify_3d_model",
  "status": "succeeded",
  "credits_charged": 20,
  "compute_ms": 29433,
  "result": {
    "schema_version": 1,
    "input_faces": 998190,
    "output_faces": 249985,
    "ratio": 0.2504,
    "max_error_units": 0.004151,
    "mesh_count": 1,
    "notes": [],
    "files": [
      {
        "name": "model.glb",
        "bytes": 21496536,
        "content_type": "model/gltf-binary",
        "url": "https://api.mcpbytes.com/blob/dl/…"
      },
      {
        "name": "model.web.glb",
        "bytes": 9527664,
        "content_type": "model/gltf-binary",
        "url": "https://api.mcpbytes.com/blob/dl/…"
      },
      {
        "name": "simplify.json",
        "bytes": 831,
        "content_type": "application/json",
        "url": "https://api.mcpbytes.com/blob/dl/…"
      }
    ]
  }
}

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": "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/simplify_3d_model/jobs \
  -H "Authorization: Bearer $MCPBYTES_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"upload_id\": \"$UPLOAD_ID\",
    \"options\": {
      \"target_faces\": 250000,
      \"web_copy\": true
    }
  }"

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.

Download from result.files or read simplify.json with read_job_file. The error combines geometric and attribute deviation; it is not a pure surface distance.

Result summary

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

• Give target_faces or ratio, not both. Without either, a quarter of the triangles is kept.
• Textured generated models keep their look down to roughly 15 to 25 % of their triangles; below that, texture seams stop the collapse. For lower counts with the look intact, use optimize_3d_model, which bakes new textures.
• The result can land above the target when max_error, seams or topology stop the collapse: result.notes says so and why. Read simplify.json for per-mesh counts and the error.
• This tool takes no job_file: download an earlier job's output and upload it.

Your agent calls simplify_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, 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/simplify_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 simplify_3d_model model.glb \
  -o target_faces=250000 -o web_copy=true --out simplified/
python scripts/mcpbytes.py read j_... simplify.json

From 10 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.

• Optimize a 3D modelRebuild with new textures when the target is below what simplification can reach.optimize_3d_model
• Create a 3D modelSimplify a generated model for web viewers: download its model.glb and upload it.create_3d_model
• Inspect a 3D modelCheck the simplified model's counts and topology.inspect_3d_model