Entropy

io.github.terradev-cloudPublished by GitHub account terradev-cloudv0.1.1Updated Oct 25, 2026

Cryptographically sound randomness for agents, with verifiable commit-reveal.

VerifiedStreamable HTTPWeb executableSecurity & MonitoringData & Analytics

Overview

AI-generated overview

Entropy gives AI assistants cryptographically sound randomness from the OS CSPRNG, plus commit-reveal records that let a third party verify a draw was not tampe

What you can do
Generate random bytes, unbiased integers, shuffles, weighted choices and samples from common distributions, including constrained per-attribute sampling with a conformance proof. Run a statistical test battery over a sequence: frequency, chi-squared, runs, longest run, serial correlation, Shannon entropy, KS and gap tests. Commit a seed to a draw spec, reveal it, execute a draw in one call, and verify the resulting chain independently of server state. Select bandit arms with epsilon-greedy, Thompson or UCB1, passing state in on each stateless call.
When to use it
Useful when an assistant must make a fair, unpredictable choice — picking a winner, shuffling an order, sampling attributes — and someone may later need to check the draw was not manipulated. Also suited to reproducible seeded draws and quick statistical sanity checks on generated sequences.
Requirements
Remote endpoint at the given URL over streamable HTTP; no authentication or environment variables are declared. The README also documents a local pip install with optional HTTP transport. Optional settings include ENTROPY_COMMITMENT_LOG, ENTROPY_STAMP_URL, ENTROPY_BEACON_URL, ENTROPY_HOST and ENTROPY_PORT; remote Stamp and drand endpoints are contacted by default.
Before you install
Commit-reveal proves a draw was not manipulated, but not that a draw was not discarded, so a party who can rerun draws can still cherry-pick. Seeds are returned to the caller and never stored server-side, so losing a seed breaks later verification. Commitment records are written to a local log file. Optional anchoring sends commitment data to the Stamp endpoint and the drand API. The test battery is informed by NIST SP 800-22 but is not certified.

Installation

In SourceWeft

  1. Open Entropy in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.terradev-cloud%2Fentropy/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "entropy": {
      "type": "http",
      "url": "https://entropy-mcp.terradev.cloud/mcp"
    }
  }
}

README

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

bash
pip install entropy-mcp          # stdio core + stamp-mcp dependencypip install entropy-mcp[http]    # adds the aiohttp HTTP transport

Quickstart

json
{"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.

ToolOperations
randombytes (CSPRNG, hex/base64) · int (unbiased [min,max] via rejection sampling) · shuffle (Fisher-Yates + permutation) · choose (weighted/unweighted, with/without replacement) · sample (uniform, normal, lognormal, exponential, triangular, beta) · constrained (independent per-attribute sampling + chi² conformance proof)
commitmentcommit (hash seed, bind draw spec, attest) · reveal (verify seed, re-execute, attest outcome) · draw (commit + execute + reveal in one call) · verify (pure third-party verification, no local state) · list (local commitment log)
testStatistical battery: frequency, chi², runs, longest run, serial, Shannon, KS, gap
exploreBandit selection: epsilon_greedy, thompson, ucb1 (stateless)

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

  1. 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.
  2. reveal takes the seed back, verifies it hashes to the committed seed_hash, re-executes the draw deterministically, and attests the outcome.
  3. verify_chain checks, independently of any server state:
CheckProves
seed_produces_commitment_hashthe revealed seed is the one committed to
commitment_attestation_validthe commitment record is intact and attested
reveal_attestation_validthe reveal record is intact and attested
commitment_precedes_revealthe commit happened before the reveal
outcome_reproduciblethe reported outcome is what the seed actually produces
params_hash_matchesthe draw spec wasn't altered after commitment
beacon_anchor_validthe commitment predates the drand round's publication (when anchored)

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

Env varDefaultPurpose
ENTROPY_COMMITMENT_LOG~/.entropy/commitments.jsonlcommitment log path (0600, capped at 10k records)
ENTROPY_STAMP_URLhttps://stamp-mcp.terradev.cloudremote Stamp endpoint (local stamp_mcp import preferred)
ENTROPY_BEACON_URLhttps://api.drand.shdrand API base
ENTROPY_HOST / ENTROPY_PORT127.0.0.1 / 8001HTTP transport bind

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.

Source: README.md at commit d8c1c0d

Tools

4

random

Direct randomness. operation selects the primitive: bytes -- raw CSPRNG bytes. params: {count<=4096, encoding: hex|base64} int -- unbiased integers in [min,max] via rejection sampling. params: {min, max, count<=10000} shuffle -- Fisher-Yates; permutation[i] is the original index now at position i. params: {items, return_permutation} choose -- k items, weighted or not, with/without replacement. params: {items, k, weights, replacement} sample -- named distributions: uniform, normal, lognormal, exponential, triangular, beta. params: {distribution, params, n<=10000} constrained -- records with independently sampled attributes + chi-squared conformance proof. params: {attributes: {attr: {value: prop}}, n} seed (top level) makes any operation reproducible.

Parametersseedparamsoperationrequired

commitment

Verifiable commit-reveal. operation selects the step: commit -- hash a seed, bind it to draw_spec {operation, params}, attest via Stamp. The seed is returned to the caller and never stored. reveal -- verify a seed against commitment_id, re-execute the draw deterministically, attest the outcome. draw -- commit + execute + reveal in one call. Pass draw_spec, or operation + params directly. verify -- pure third-party verification of commitment_record + reveal_record. No local state. list -- read-only view of the local commitment log (limit, since).

Parametersseedlimitsinceattesteddraw_specoperationrequireddescriptionanchor_beaconcommitment_idreveal_recordcommitment_record

test

Statistical battery over a sequence: frequency, chi-squared, runs, longest run, serial correlation, Shannon entropy, KS, gap test. Informed by NIST SP 800-22; no certification claimed. sequence is a list of numbers, list of strings, or a hex/base64 byte string.

Parametersalphatestsexpectedsequencerequiredinput_typedist_paramsdistribution

explore

Bandit arm selection: epsilon_greedy, thompson, or ucb1. Stateless -- caller passes state in as {arm: {pulls, successes, total_reward}} and gets a selection back. params: {epsilon} for epsilon_greedy.

Parametersarmsrequiredseedstateparamsstrategyrequired

Version history

1
  1. v0.1.1LatestSep 27, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.