entropy-mcp
Entropy gives agents randomness they cannot produce themselves, and proof they did not manipulate it.
The evidence
Language models cannot generate statistically sound randomness. This is measured, not speculative:
- arXiv:2601.05414 — 11 frontier models, 15 distributions: 7% median pass rate in batch mode; 10 of 11 models passed zero distributions in stateless mode.
- arXiv:2604.06543 — the knowing-doing gap: models can describe correct sampling and still fail to do it. Asking a model to generate its own seed reproduces the same bias.
- arXiv:2606.06622 — UnpredictaBench: models are measurably predictable where they should be random.
The stateless point
Agents operate in exactly the regime where models fail hardest: independent, stateless calls with no memory of prior draws. Every "pick a random number" an agent answers from its own weights is a draw from a biased, predictable source. Entropy moves the draw out of the model and into the OS CSPRNG — and the commit-reveal chain proves the draw that happened is the draw that was reported.
Install
pip install entropy-mcp # stdio core + stamp-mcp dependency
pip install entropy-mcp[http] # adds the aiohttp HTTP transport
Quickstart
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"commitment","arguments":{
"operation":"draw",
"draw_spec":{"operation":"shuffle","params":{"items":["alice","bob","carol","dave"]}},
"description":"who goes first"}}}
One call returns the shuffled list plus a commitment record, a reveal record, and a verification block — the full chain a third party can check with commitment operation:"verify".
Command reference
Four tools. operation selects the primitive; params carries its arguments; seed makes any draw reproducible.
Every seeded command is deterministic given its inputs and seed — byte-identical across processes, machines, and Python versions. Only the raw OS-entropy paths are non-deterministic, and they say so.
How commit-reveal works
- commit generates (or accepts) a 32-byte seed, stores only
sha256(seed), binds it to your draw spec via canonical hash, timestamps it via Stamp's NTP, optionally anchors it to a drand round, and attests the whole record. The seed goes to you. It is never stored server-side. - reveal takes the seed back, verifies it hashes to the committed
seed_hash, re-executes the draw deterministically, and attests the outcome. - verify_chain checks, independently of any server state:
What this is not
- Not a statistics package — the summary block and test battery are conveniences, not an analysis suite.
- Not a simulation engine — no Monte Carlo, no sensitivity analysis, no fitting.
- Not a randomness beacon — drand anchoring is optional hardening, not a source.
- Not NIST-certified — the test battery is informed by SP 800-22, in the spirit of it.
Configuration
Threat model
See THREAT_MODEL.md. The honest summary: Entropy proves a draw was not manipulated; it cannot prove a draw was not discarded.
License
Apache 2.0.