---
name: mcpbytes
description: Run MCPBytes file-processing tools (api.mcpbytes.com) - split a 3D model (.glb .gltf .obj .ply .stl .off .blend) into part meshes with colliders and physics metadata, or extract the text of a PDF page by page. Use when the user wants a 3D model separated into parts or segmented, needs the text of a PDF file or PDF URL, or mentions MCPBytes. Works through the MCPBytes MCP tools when they are connected, otherwise through the REST API with the bundled script.
---

# MCPBytes

MCPBytes runs each tool as a **job**: one input file in, output files and a small result summary out. Jobs take
from 2 seconds (PDF text) to about a minute (3D models). Outputs are kept for 24 hours.

| Tool | Input | Output | Details |
|---|---|---|---|
| `split_3d_model` | `.glb .gltf .obj .ply .stl .off .blend` | part meshes, convex colliders, `manifest.json`, one `.zip` of everything | [references/split_3d_model.md](references/split_3d_model.md) |
| `extract_pdf` | `.pdf` | `text.txt` with `--- Page N ---` markers, `pages.json` | [references/extract_pdf.md](references/extract_pdf.md) |
| `inspect_3d_model` (when enabled) | `.glb .gltf .obj .ply .stl .off .blend` | geometry, units and topology in `inspection.json`, `summary.txt` | [references/inspect_3d_model.md](references/inspect_3d_model.md) |

The list above can be out of date: `GET /v1/tools` (or `python scripts/mcpbytes.py tools`) returns the tools that
exist now, with each tool's options as JSON Schema and the user's limits. Read a tool's details file before using it.

## Pick the interface

1. **MCP tools are connected** (you can see `create_upload`, `get_job`, `read_job_file` and a tool such as
   `extract_pdf`): use them. See "With MCP".
2. **No MCP tools**: use `scripts/mcpbytes.py` (Python 3.9+, standard library only). It needs an API key in the
   `MCPBYTES_API_KEY` environment variable. See "Without MCP".

If neither works because there is no key, tell the user to create one at https://console.mcpbytes.com/keys and to
set `MCPBYTES_API_KEY`. Never ask the user to paste the key into the chat, never print it, and never write it to a file.

## With MCP

1. **Input.** For a public `https` URL, pass `url` to the tool (add `filename` if the URL does not end in the file's
   extension, e.g. `paper.pdf`). For a local file, call `create_upload` with the file name, run the `curl` command it
   returns to PUT the file, then pass the returned `upload_id` to the tool. Upload URLs work once and expire after
   an hour.
2. **Run.** Call a tool returned by discovery (`split_3d_model`, `extract_pdf`, `inspect_3d_model`). Options are flat arguments. It waits up to `wait_seconds`
   (at most 45) and returns the job.
3. **Wait.** If the job is still `queued` or `running`, call `get_job` with the `job_id` and `wait_seconds: 45` until
   the status is final. Do not start the same job again: it would be charged again. To retry safely after a
   network error, repeat the call with the same `idempotency_key`.
4. **Results.** `result.files` lists every output with a download `url` (valid up to 24 hours; `get_job` gives fresh
   ones). Read text outputs (`.txt .json .md .csv`) with `read_job_file`: it returns a chunk and `next_offset`; pass
   that as `offset` until `eof`. Read only as much as the task needs. Download other files with `curl -fsSLo`.

## Without MCP

```bash
python scripts/mcpbytes.py tools                                   # tools, options, prices, your limits
python scripts/mcpbytes.py run extract_pdf paper.pdf --out out/    # upload, wait, download every output
python scripts/mcpbytes.py run extract_pdf https://example.com/a.pdf --filename a.pdf -o max_pages=20 --out out/
python scripts/mcpbytes.py run split_3d_model chair.glb -o detail=high --out parts/
python scripts/mcpbytes.py job j_...                               # status and result of a job
python scripts/mcpbytes.py read j_... text.txt --offset 0 --limit 20000   # a chunk of a text output
```

`run` prints the job as JSON on stdout (progress goes to stderr) and exits non-zero if the job failed. `--no-wait`
returns right after the job is created; `--out` is optional (without it, nothing is downloaded: use `read`).

The same API with plain HTTP, if Python is not available: `POST /v1/tools/{tool}/jobs?filename=<name>&<option>=<value>`
with the file as the body and `Authorization: Bearer $MCPBYTES_API_KEY`, then `GET /v1/jobs/{id}` until the status is
final, then `GET /v1/jobs/{id}/files/{name}?offset=&limit=` for text or the file's `url` for a download. The full
contract is https://api.mcpbytes.com/openapi.json.

## Credits

Jobs cost the user's prepaid credits, by the size of the input. Each tool states its price: in its MCP description,
and as `pricing` in `GET /v1/tools` (`mcpbytes.py tools`). `GET /v1/me` has the balance (`credits.balance`), and a
finished job shows `credits_charged`. A job that fails costs nothing. Before a job that is large for the balance, or
before running the same file again with other options, tell the user what it costs.

## Errors and limits

- A failed job has `error.code`, `error.message` and often `error.hint`: tell the user what the hint says instead of
  retrying blindly. `unsupported_format`, `invalid_pdf`, `encrypted_pdf`, `invalid_mesh` and `limit_exceeded` will
  fail again with the same file.
- `402` or a failed job with `insufficient_credits`: the balance is too low, and the message says what the job costs.
  Tell the user; only they can add credits (https://console.mcpbytes.com/billing). For a PDF, fewer pages
  (`max_pages`) cost less.
- HTTP `429` (`too_many_active_jobs`, `quota_exceeded`) and `503` (`busy`) carry `Retry-After`: wait that long, once.
  Do not work around a limit.
- `401`: the key is missing, wrong or revoked.
- Files are the user's data: send only the file the user asked about, and say that it is uploaded to MCPBytes.