mcpField
D
D20DAO Verifiable Randomness

D20DAO Verifiable Randomness

Local
d20dao.orgDeveloper Tools0Updated 3w ago
RepositoryVisit website

About D20DAO Verifiable Randomness

D20DAO provides AI agents with verifiable random draws on Arc, including dice, selections and shuffles. Its MCP server uses a Circle Agent Wallet for payment and returns links to replayable proofs.

Key features

  1. 01Verifiable random draws
  2. 02Dice, ranges, picks, and shuffles
  3. 03Free result lookup
  4. 04Setup and spending checks
  5. 05Replayable proof links

Use cases

  1. 01Run a provable raffle
  2. 02Choose a random item or winner
  3. 03Generate dice or coin-flip results

MCP support

The MCP server exposes tools for drawing randomness, retrieving results, and checking setup status. Draws cost 0.05 USDC and are paid through the Circle CLI.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "org-d20dao-vrf": {
      "command": "npx",
      "args": [
        "-y",
        "@d20dao/mcp"
      ],
      "env": {
        "D20_DAILY_LIMIT_USDC": "<D20_DAILY_LIMIT_USDC>",
        "D20_NETWORK": "<D20_NETWORK>",
        "D20_PAY_CHAIN": "<D20_PAY_CHAIN>",
        "D20_WALLET_ADDRESS": "<D20_WALLET_ADDRESS>",
        "D20_CIRCLE_CLI": "<D20_CIRCLE_CLI>",
        "D20_MCP_HOME": "<D20_MCP_HOME>"
      }
    }
  }
}
Run commandnpx -y @d20dao/mcp
Environment variables to set
D20_DAILY_LIMIT_USDCSpending cap per UTC day in USDC (default 1; 0 turns paid draws off).
D20_NETWORKArc Mainnet (default) or Arc Testnet.
D20_PAY_CHAINCircle CLI chain code to pay from, such as ARC or BASE (default: first funded).
D20_WALLET_ADDRESSAgent wallet to pay from (default: the first one the Circle CLI lists).
D20_CIRCLE_CLIPath to the Circle CLI's dist/index.js (default: circle on PATH).
D20_MCP_HOMEFolder for the daily spending record (default ~/.d20dao-mcp).

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
npm@d20dao/mcp0.1.2

Tools

3

Saved tool list · updated 3w ago

ParameterTypeRequiredDescription
maxanyNorange only, required: highest value, inclusive, at least min.
minanyNorange only, required: lowest value, inclusive.
seedstringNoContext bound on chain to this draw, such as "raffle-7 round 2" (at most 64 bytes). Use a new seed for each separate draw. To commit to an item list, put its hash here.
countintegerNodice: rolls, 1 to 128 (default 1). chooseMany: distinct picks, required.
itemsarrayNochooseOne, chooseMany, shuffle: labels to draw from (1 to 256, each at most 200 bytes). Only their count is proven; the answer adds picked. Give this or population.
sidesanyNodice only, required: faces per die, at least 2.
operationenumYesraw: one 256-bit word. coinFlip: 0 (tails) or 1 (heads). dice: count rolls of 1 to sides. range: one integer from min to max. chooseOne: one zero-based index. chooseMany: count distinct indices. shuffle: every index once.raw | coinFlip | dice | range | chooseOne | chooseMany | shuffle
populationintegerNochooseOne, chooseMany, shuffle: how many to draw from, 1 to 256. Give this or items.

Details

From the project README

D20DAO MCP server

Verifiable randomness for AI agents: dice, coin flips, ranges, winners and shuffles, each one a VRF request on Arc with a proof anyone can replay. 0.05 USDC per draw, paid from your Circle Agent Wallet.

Draws run on Arc through the D20DAO x402 API. D20DAO also runs on Robinhood Chain, where there is no x402 API: a contract there requests randomness directly on chain, using @d20dao/vrf-sdk 0.6.2 and its integration guide.

Setup

  1. Wallet. Have your agent follow Circle's setup guide. It installs the Circle CLI, logs you in with an emailed code and creates an agent wallet. You accept Circle's terms yourself.

  2. Funds. Fund the wallet with USDC and deposit some into Circle Gateway, for example on Arc:

    circle gateway deposit --chain ARC --method direct --amount 1 --address <wallet>

    Arc, Polygon, Avalanche, Base, Arbitrum, Optimism, Unichain and Ethereum balances all work.

  3. Server. Add it to your client.

    Claude Code:

    claude mcp add d20dao -- npx -y @d20dao/[email protected]

    Claude Desktop, Cursor and others (mcpServers in the client's MCP config):

    { "mcpServers": { "d20dao": { "command": "npx", "args": ["-y", "@d20dao/[email protected]"] } } }

    On Windows, use "command": "cmd" with "args": ["/c", "npx", "-y", "@d20dao/[email protected]"] if the client cannot start npx directly. Pin the version, since the server runs with your Circle session.

Ask your agent to call setup_status; it names the next step until everything is ready.

Tools

ToolCostDoes
draw0.05 USDCraw, coinFlip, dice (up to 128), range, chooseOne, chooseMany, shuffle (up to 256 items). Returns the result with request, fulfillment and proof links.
get_resultfreeReads a draw by paymentId or a request by requestId.
setup_statusfreeChecks the CLI, login, wallet, Gateway balance and today's spending.

An optional seed (up to 64 bytes) is bound on chain to the draw, so a raffle can name its round before the result exists. Give each separate draw its own seed: an identical draw within five minutes returns the earlier one without paying.

A draw usually answers in about ten seconds, but it can take longer. If your client's tool timeout is short (60 seconds is a common default), raise it; a retry after a timeout returns the same draw rather than paying twice.

Settings

VariableDefault
D20_DAILY_LIMIT_USDC1Spending cap per UTC day, shared by every server process of the user. 0 turns paid draws off.
D20_NETWORKmainnettestnet uses the Arc Testnet API and a testnet CLI login (circle wallet login <email> --testnet).
D20_PAY_CHAINfirst fundedCircle CLI chain code to pay from, such as ARC or BASE.
D20_WALLET_ADDRESSfirst agent walletAgent wallet to pay from.
D20_CIRCLE_CLIcircle on PATHPath to the CLI's dist/index.js.
D20_MCP_HOME~/.d20dao-mcpWhere the spending record is kept.

Safety

  • The server holds no keys. The Circle CLI signs, and your Circle wallet limits apply. It never accepts Circle's terms for you: CIRCLE_ACCEPT_TERMS is kept out of the CLI it runs, and DO_NOT_TRACK is set so your item labels stay out of the CLI's telemetry.
  • It pays only api.d20dao.org (or api-testnet.d20dao.org) and never more than 0.05 USDC per draw. If the CLI ever reports another seller, that draw comes back with a warning and paid draws stop until you delete halt.json from the server's home folder.
  • Each draw reserves its price in the daily record before paying; if the record cannot be written, it does not pay.
  • A draw that is still pending is finished for free with get_result. If the answer is lost after payment, the server resends the payment the CLI signed, which the API honours at most once.
  • A result says charged: false only when that is known. When it says unknown, do not draw again; check with get_result or the wallet.
  • draw is marked as a tool with side effects, so clients ask before running it unless you allow it.

Verify

Every result links its request and fulfillment transactions and a proof page. Replay the proof yourself with @d20dao/vrf-sdk 0.6.2 or later; see verification and the agent API guide.

License

MIT

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.