Documentation

1. 1. Create an API key

   Sign in to the console with GitHub and create a key. Keys start with mcpb_ and work for MCP and the REST API. The samples read it from MCPBYTES_API_KEY.

   Get an API key

2. 2. Connect your agent

   Add the MCPBytes server to Claude Code, or to any MCP client (see MCP). Then ask your agent to use a tool: for example, to split a 3D model into parts.

   Claude Code

   # Sign in with GitHub when prompted
   claude mcp add --transport http mcpbytes \
     https://api.mcpbytes.com/mcp
   
   # Or use an API key
   claude mcp add --transport http mcpbytes \
     https://api.mcpbytes.com/mcp \
     --header "Authorization: Bearer $MCPBYTES_API_KEY"

3. 3. Or call the REST API

   Send a file to a tool and poll the job until its files are ready. To try a tool without writing code, use the console.

   cURLNode.js

   # 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

The MCP server is at https://api.mcpbytes.com/mcp (Streamable HTTP). Clients that support OAuth sign in with GitHub; others send an API key as a bearer token.

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

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

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

{
  "inputs": [
    {
      "type": "promptString",
      "id": "mcpbytes-api-key",
      "description": "MCPBytes API key (mcpb_...)",
      "password": true
    }
  ],
  "servers": {
    "mcpbytes": {
      "type": "http",
      "url": "https://api.mcpbytes.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:mcpbytes-api-key}"
      }
    }
  }
}

{
  "mcpServers": {
    "mcpbytes": {
      "httpUrl": "https://api.mcpbytes.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MCPBYTES_API_KEY}"
      }
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcpbytes": {
      "type": "remote",
      "url": "https://api.mcpbytes.com/mcp",
      "enabled": true,
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:MCPBYTES_API_KEY}"
      }
    }
  }
}

{
  "mcpServers": {
    "mcpbytes": {
      "type": "http",
      "url": "https://api.mcpbytes.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MCPBYTES_API_KEY}"
      }
    }
  }
}

mkdir -p ~/.pi/agent/skills/mcpbytes
curl -fsSL https://mcpbytes.com/skills/mcpbytes/mcpbytes.tar.gz \
  | tar -xz -C ~/.pi/agent/skills/mcpbytes

- insert:
    - id: mcp-mcpbytes
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: mcpbytes
        transport: streamable-http
        url: https://api.mcpbytes.com/mcp
        headers:
          Authorization: !!js '`Bearer ${process.env.MCPBYTES_API_KEY}`'

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

extensions:
  mcpbytes:
    type: streamable_http
    name: mcpbytes
    enabled: true
    uri: "https://api.mcpbytes.com/mcp"
    headers:
      Authorization: "Bearer ${MCPBYTES_API_KEY}"
    env_keys:
      - MCPBYTES_API_KEY
    timeout: 300

{
  "context_servers": {
    "mcpbytes": {
      "url": "https://api.mcpbytes.com/mcp"
    }
  }
}

https://api.mcpbytes.com/mcp

{
  "mcpServers": {
    "mcpbytes": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.mcpbytes.com/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization:${MCPBYTES_AUTH}"
      ],
      "env": {
        "MCPBYTES_AUTH": "Bearer <your key>"
      }
    }
  }
}

Every tool is one MCP tool that starts a job. For a local file, the agent calls create_upload, PUTs the file to the returned URL, then calls the tool with the upload_id. For a public https URL it calls the tool directly. The tool and get_job wait up to wait_seconds (at most 45) for the result, and read_job_file reads text outputs such as manifest.json in chunks.

To give an agent a shorter tool list, connect to one family of tools instead: https://api.mcpbytes.com/mcp/3d, https://api.mcpbytes.com/mcp/pdf. Each has its tools plus the shared ones; every tool's page shows the setup for its endpoint.

Agent skill

The MCPBytes skill teaches an agent the whole workflow: uploads, waiting for jobs, reading results in chunks, each tool's options and errors. With MCP connected it uses the MCP tools; without MCP (pi, for example) it drives the REST API through a small Python script and MCPBYTES_API_KEY. Most agents (Codex, Gemini CLI, Copilot, Cursor, OpenCode, pi and more) read it from ~/.agents/skills/; the skill page has every agent's folder, Claude Code's included.

mkdir -p ~/.agents/skills/mcpbytes
curl -fsSL https://mcpbytes.com/skills/mcpbytes/mcpbytes.tar.gz \
  | tar -xz -C ~/.agents/skills/mcpbytes

The base URL is https://api.mcpbytes.com/v1. Authenticate every request with your API key as a bearer token.

# Every request authenticates with an API key
curl https://api.mcpbytes.com/v1/me \
  -H "Authorization: Bearer $MCPBYTES_API_KEY"

The full contract, with every field and response, is in the OpenAPI description. API keys are managed in the console.

Every run is a job. Creating one returns 202 with the job; poll GET /v1/jobs/{id} until its status is final.

Sending a file

Send the file itself as the request body with ?filename= (options go in the query string, as in the quickstart), use an upload URL, or give a public https URL. The JSON forms take options in an options object.

# 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\"}"

To retry safely, send an Idempotency-Key header: a repeated key returns the original job with 200 instead of starting a new one.

Results and downloads

A succeeded job lists its files in result.files, each with a download url. URLs are valid for up to 24 hours; fetch the job again for fresh ones. Results are deleted after 24 hours, or sooner with DELETE /v1/jobs/{id}. Text outputs (.txt .json .md .csv) can also be read in chunks, without downloading them: GET /v1/jobs/{id}/files/{name}?offset=&limit= returns text and the next_offset to continue from, until eof.

Jobs are paid with prepaid credits, and one balance pays for every tool. A new account starts with 100 free credits. GET /v1/me returns your balance (credits), GET /v1/tools every tool's price (pricing), and GET /v1/billing where your credits went.

A job's price follows the size of its input, so it is charged when the file has been opened and measured, before the work starts. The job then shows credits_charged. Starting a job needs the tool's smallest price in the balance (402 insufficient_credits otherwise). A job that fails costs nothing: its charge goes back, and credits_charged reads 0.

Every account has the same limits. GET /v1/me returns yours and your current usage.

Errors return JSON: {"error": {"code": "…", "message": "…"}}. Codes are stable; messages may change. Over MCP, the same code and message come back as a tool error.

A failed job is still returned with 200; its error says why. Common codes:

• 3D Model Mesh Segmentation

  Tool page

  Split a 3D model into separate part meshes, with colliders and physics metadata.

  MCP tool

  split_3d_model

  REST

  POST /v1/tools/split_3d_model/jobs

  Price

  From 20 credits

  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

  Options

  detail

  low | medium | highHow finely to split: low = major assemblies, high = sub-parts. Default medium.

  format

  glb | obj | plyPart file format. Default glb.

  max_parts

  1–64Safety ceiling on the part count, which is chosen automatically. Capped at 32.

  min_part_faces

  integerMerge parts with fewer faces. Default 0.

  min_part_area

  0–1Merge parts below this fraction of the surface area. Default depends on detail.

  preprocess

  auto | on | offConnectivity cleanup of the working mesh. Default auto.

  segmented

  true | falseAlso write segmented.glb, all parts color-coded. Default true.

  density

  numberMass per cubic model unit, for mass estimates. Default 100.

• PDF Text Extraction

  Tool page

  Extract the text of a PDF, page by page, in chunks an agent can read.

  MCP tool

  extract_pdf

  REST

  POST /v1/tools/extract_pdf/jobs

  Price

  1 credit per 25 pages

  Input format

  .pdf (not password-protected)

  Pages

  Up to 500 per job; continue with start_page

  Outputs

  text.txt with page markers, pages.json with page offsets and metadata

  Reading

  First bytes inline over MCP; the rest in chunks of up to 100,000 bytes

  Scanned pages

  No OCR: pages without a text layer come back empty

  Options

  start_page

  integer ≥ 1First page to extract. Default 1.

  max_pages

  integer ≥ 1Extract at most this many pages. Capped at 500. Fewer pages cost fewer credits.

• 3D Model Inspection

  Tool page

  Check geometry, dimensions, materials and topology before splitting a model.

  MCP tool

  inspect_3d_model

  REST

  POST /v1/tools/inspect_3d_model/jobs

  Price

  From 10 credits

  Formats

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

  Outputs

  inspection.json and summary.txt

  Dimensions

  World-space bounds; units unknown when unspecified

  Topology

  Components, boundary edges, non-manifold edges, degenerate faces and watertightness

  Blender

  Evaluated meshes; pack resources into the file

  Options