Extract text from a PDF

Send a PDF and MCPBytes returns its text with a marker before every page. Agents get the beginning inline and read on in chunks, so a long document never floods the context. pages.json locates every page in the text and carries the document's metadata.

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

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 PDF is the request body
curl "https://api.mcpbytes.com/v1/tools/extract_pdf/jobs?filename=paper.pdf" \
  -H "Authorization: Bearer $MCPBYTES_API_KEY" \
  --data-binary @paper.pdf

{
  "id": "j_7c2m9x4f1q8w3e6r5t0y2u7i9o",
  "tool": "extract_pdf",
  "status": "queued",
  "input": {
    "name": "paper.pdf",
    "bytes": 1204331,
    "source": "body"
  },
  "options": {
    "start_page": 1,
    "max_pages": 500
  },
  "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"

# Read the text, 20,000 bytes at a time
curl "https://api.mcpbytes.com/v1/jobs/$JOB_ID/files/text.txt?offset=0" \
  -H "Authorization: Bearer $MCPBYTES_API_KEY"

{
  "id": "j_7c2m9x4f1q8w3e6r5t0y2u7i9o",
  "tool": "extract_pdf",
  "status": "succeeded",
  "result": {
    "files": [
      {
        "name": "pages.json",
        "bytes": 1842,
        "sha256": "…",
        "url": "https://api.mcpbytes.com/blob/dl/j_7c2m9x4f1q8w3e6r5t0y2u7i9o/pages.json?t=…"
      },
      {
        "name": "text.txt",
        "bytes": 48903,
        "sha256": "…",
        "url": "https://api.mcpbytes.com/blob/dl/j_7c2m9x4f1q8w3e6r5t0y2u7i9o/text.txt?t=…"
      }
    ],
    "pages": 12,
    "first_page": 1,
    "last_page": 12,
    "empty_pages": 0,
    "chars": 48211,
    "notes": []
  },
  "compute_ms": 1310,
  "credits_charged": 1,
  "finished_at": "2026-09-19T12:00:03.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": "paper.pdf"}'

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

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

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.

Read text.txt in chunks with GET /v1/jobs/{id}/files/text.txt?offset=&limit= (or read_job_file over MCP): pass next_offset as the next offset until eof. A page's offset in pages.json takes you straight to it.

Result summary

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

• Read text.txt in chunks: pass next_offset as the next offset until eof, and stop once you have what the task needs.
• To go straight to page N, read pages.json and use that page's offset and bytes as offset and limit.
• For a long document, extract only the range you need with start_page and max_pages. Fewer pages cost less.
• Text follows the page layout: tables and multi-column pages may need care when quoting.
• There is no OCR. Scanned pages come back empty; empty_pages counts them, and a note says when no text was found at all.

Your agent calls extract_pdf. Connect it to https://api.mcpbytes.com/mcp/pdf for this tool, or to https://api.mcpbytes.com/mcp for every tool.

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

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

{
  "mcpServers": {
    "mcpbytes": {
      "url": "https://api.mcpbytes.com/mcp/pdf",
      "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/extract_pdf.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 extract_pdf paper.pdf --out out/
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 read j_... text.txt --offset 0

1 credit per 25 pages. 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.