Documentation

Every tool runs as a job, the same way over MCP and over the REST API:

1. 1

   Start a job

   Send the tool its input: a file, a public URL, or parameters such as a prompt. The response is the job.

2. 2

   Wait for it

   Poll the job until its status is final. Over MCP, the tool call waits for you, up to 45 seconds at a time.

3. 3

   Use the results

   Download the files in result.files, or read text outputs in chunks. Results are kept for 1 day on Free, 7 days on Pay as you go and 30 days with a monthly bundle.

Jobs are paid with prepaid credits, and a job that fails costs nothing. The details are in Jobs & files and Credits & prices.

1. 1Create an API key

   Sign in to the console with GitHub or an email link 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. 2Connect your agent

   Add the MCPBytes server to Claude Code, or to any MCP client. Then ask your agent to use a tool: for example, to turn a sentence into an image.

   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. 3Or call the REST API

   Submit a tool's input and poll the job until its files are ready (REST API). To try a tool without writing code, use the console.

   create-sprite.sh

   curl https://api.mcpbytes.com/v1/tools/create_pixel_sprite/jobs \
     -H "Authorization: Bearer $MCPBYTES_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "options": {"description": "A forest ranger with a green hood and a brown satchel", "seed": 42},
       "idempotency_key": "pixel-sprite-example-004"
     }'

• Connect over MCPAdd the MCPBytes server to your agent, pick a toolset, and let the agent upload files, run jobs and read results.
• REST APIAuthenticate, send a file, a URL or parameters, and retry safely with idempotency keys.
• Jobs & filesJob statuses, long-running jobs, canceling, downloads, reading text outputs and chaining one job into the next.
• Credits & pricesHow jobs are charged, when failed jobs are refunded, and every tool's price.
• Limits & errorsAccount and tool limits, the error format, HTTP errors and job errors, and how to handle them.

Each tool has its own reference: input, options, outputs, pricing, limits and errors, with samples for MCP and REST.