# get_random_numbers

Discover availability and pricing through `GET /v1/tools` or MCP tools/list. Request hardware-generated random
integers within an inclusive range. No file is needed.
Use `/mcp/random` for this tool family, or `/mcp` for the complete catalog.

Options are `count` (1–1000, default 1), `min` and `max` (inclusive signed 32-bit bounds,
defaults 0 and 2147483647, with min < max). Repeated values are allowed. There is no deterministic
seed or uniqueness promise. `idempotency_key` is required: reuse the key and options to recover
the same job after a network failure; use a new key for fresh numbers. Conflicting options return
409. A deleted job's key returns 410 while its tombstone remains.

MCP waits up to 30 seconds by default; override `wait_seconds` from 0 to 45. If the job remains
queued/running, poll `get_job` rather than submitting another job. REST returns 202 for new jobs
and 200 for matching replays. Queued jobs can be canceled; running jobs cannot.

Outputs are `numbers.json` and `numbers.txt`. The latter is the same integer array, returned
inline over MCP when ready. JSON contains `numbers`, `count`, `min` and `max`.

Each new job draws fresh randomness from physical hardware. Choose this tool when an external
source of chance matters for random choices, tie-breaks, dice rolls, sampling candidates or
supplying random inputs to simulations.
A seeded software generator such as `rand()` follows a repeatable sequence; use a local seeded
generator when you need reproducible simulation runs. Do not use this tool for passwords,
cryptographic keys or wallet seeds.

MCPBytes tested one million output bits using the NIST Statistical Test Suite: 184 of 188
component checks passed, with four pattern checks flagged. Read our results and download
the sample at https://mcpbytes.com/verification/random-numbers.

Without MCP, set `MCPBYTES_API_KEY` privately and use the bundled client:

```bash
python scripts/mcpbytes.py run get_random_numbers \
  -o count=10 -o min=1 -o max=6 \
  --idempotency-key dice-example-001 --out numbers/
```

Read the catalog price before submitting. A failed charged job is refunded. `source_unavailable`,
`source_unhealthy`, `invalid_output` and `timeout` mean generation could not complete. Report the
failure rather than repeatedly resubmitting or substituting your own numbers.