Get random numbers

A seeded generator such as rand() follows a repeatable sequence. MCPBytes draws fresh randomness from physical hardware for each new job. Use it when you want an external source of chance to pick a creative direction, break a tie, roll dice, sample candidates or supply random inputs to simulations. Your agent sets the count and range and gets integers back through MCP or REST, with no local random generator to configure. Repeated values are allowed. Not for cryptographic secrets.

Randomness

Hardware-generated; fresh draws for new jobs

Input

count, min and max; no file

Outputs

numbers.json and numbers.txt

Range

Signed 32-bit bounds, min less than max

Replay

Reuse a request key to retrieve the same draw

14 test groups passed every check in our NIST test run on one million output bits. Explore the complete results and what each check means. NIST Randomness validation

Send the options as JSON. 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/get_random_numbers/jobs \
  -H "Authorization: Bearer $MCPBYTES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"options":{"count":10,"min":1,"max":6},"idempotency_key":"dice-example-001"}'

{
  "id": "j_vwzd6fj7kgy9c4xzn3d3nd922t",
  "tool": "get_random_numbers",
  "status": "succeeded",
  "input_kind": "parameters",
  "options": {
    "count": 10,
    "min": 1,
    "max": 6
  }
}

curl "https://api.mcpbytes.com/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $MCPBYTES_API_KEY"

{
  "id": "j_vwzd6fj7kgy9c4xzn3d3nd922t",
  "tool": "get_random_numbers",
  "status": "succeeded",
  "result": {
    "numbers": [
      5,
      4,
      3,
      6,
      1,
      3,
      2,
      5,
      2,
      6
    ],
    "count": 10,
    "min": 1,
    "max": 6,
    "files": [
      {
        "name": "numbers.json"
      },
      {
        "name": "numbers.txt"
      }
    ]
  }
}

A job can be canceled while it is queued: POST /v1/jobs/{id}/cancel.

More on statuses, downloads and retention in Jobs & files.

No file. Send the options in a JSON body, {"options": {…}}, or as arguments of the MCP tool. Keep private text such as prompts out of URLs.

Put options in the options object of the 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.

New jobs return HTTP 202. Replaying a completed request returns HTTP 200, as in the example. Download links last up to 24 hours, capped by output retention. Use a new idempotency key for fresh numbers; reuse a key to recover the same job after a network failure.

Result summary

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

• Reuse the idempotency key and options to recover the same draw after a network failure. Use a new key for fresh numbers; reusing a key with other options returns 409.
• Repeated values are allowed, and there is no seed or uniqueness guarantee. For reproducible simulation runs, use a seeded local generator.
• Not for passwords, cryptographic keys or wallet seeds. For key material, use get_random_bytes through MCPBytes Vault.
• Over MCP the numbers come back with the result. A queued job can be canceled; a running one cannot.

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

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

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

{
  "mcpServers": {
    "mcpbytes": {
      "url": "https://api.mcpbytes.com/mcp/random",
      "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/get_random_numbers.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 get_random_numbers \
  -o count=10 -o min=1 -o max=6 --out numbers/

1 credit per job. The price is charged before paid processing starts. 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.

• Create a secretKey material and random tokens, saved locally so your agent only sees a reference.get_random_bytes