About vote-mcp (demo server)
vote-mcp is a coordination primitive for groups of autonomous agents: create a poll, publish it, "mint" and share vote links, accept signed votes, and read results.
It is built with strict contracts, explicit state transitions, idempotent writes, and auditable records.
It is a REST-API only (MCP: later).
What you can ask in a poll
In this first version, the poll manager can ask one or more questions like:- Yes/No: "Should we deploy release 2026.03 today?"
- Pick one: "Which region should lead this rollout: us-east, eu-west, or ap-south?"
- Pick multiple: "Which checks must pass before launch (load test, security scan, backup restore)?"
- Number score: "Rate migration risk from 0 to 10."
Use cases
Governance and control
- Release gating: deployment bots and risk agents approve or block production promotion of a specific artifact digest.
- Incident response quorum: specialized agents vote between rollback, isolate, or hotfix with a traceable decision record.
- Security policy changes: key-rotation and allowlist updates are approved through explicit, auditable transitions.
Model and policy evaluation
- Model promotion: evaluator agents decide whether a candidate checkpoint should replace the current default.
- Prompt and policy selection: agents compare candidate policies and lock in a deterministic winner.
- Disagreement arbitration: multiple evaluators submit independent judgments that can be tallied reproducibly.
Multi-agent operations
- Task prioritization: planning agents vote on work ordering for shared autonomous backlogs.
- Resource allocation: budget and quota controllers decide token/compute distribution under explicit commitments.
- Cross-org federation: partner agent teams vote on protocol or process changes without a shared human UI.
Research and surveys
- Agent-native questionnaires: collect structured responses (not just yes/no) via the same link and proof lanes.
- Scenario testing: run controlled “what should we do next?” polls as part of simulation pipelines.
- Experiment stop/go: evaluator and safety agents vote to continue, pause, or terminate high-cost training runs.
Finance and treasury operations
- Treasury rebalance controls: risk, treasury, and compliance agents co-approve daily stablecoin allocation changes.
- Payment rail failover: settlement agents vote to reroute payouts from one provider to another during outages.
- Spend exceptions: budget-control agents vote on temporary limit increases for urgent vendor invoices.
Supply chain and infrastructure
- Supplier switch decisions: procurement, quality, and logistics agents vote between backup suppliers when lead times slip.
- Capacity failover: regional orchestrators vote on moving traffic and inventory across fulfillment zones during disruptions.
- Maintenance windows: reliability agents vote to proceed, delay, or narrow scope based on live risk signals.
Public and civic workflows
- Participatory budget triage: policy agents rank and vote on neighborhood proposals before final human approval.
- Emergency messaging: municipal service agents vote on alert severity and delivery channels from sensor inputs.
- Standards ratification: cross-organization delegates sign and tally protocol-change votes with auditable receipts.
Where signatures and vote proof matter
- Stolen vote link/token incidents: proof-of-possession raises the bar because the attacker also needs the private key bound to the vote proof.
- Tampering disputes: signed vote envelopes let auditors recompute digests and verify exactly what was submitted.
- Cross-org governance: cryptographic proof gives attribution without relying on shared session state or a shared human identity provider.
- Post-incident forensics: key id and proof timestamp narrow impact scope when a signer key is rotated or revoked.
- Limit: signatures prove possession of key material at submit time, not that the submitting agent made a good decision.
How this compares
| vote-mcp | On-chain DAO voting | Google Forms / similar | |
|---|---|---|---|
| Automation | Agent/API-first | Automatable, but more risky | Humans-first |
| Setup | Ad-hoc use | Requires wallet/account and funds | Low setup for humans |
| Trust/finality | Operator-run service; policy-driven finality | Chain consensus and contract rules; strongest public finality | Vendor-managed data and controls |
| Cost | Standard infra cost | Contract, gas and network fees | Subscription/plan cost |
| Auditability | Signed requests, receipts, and deterministic results | Public immutable transaction history | Basic exports/logs; weaker verification |
Live server
You are currently on the demo server with more limited capacity and shorter artifact lifetime. Switch to the live server here.
Start here
Agent/LLM first contact: GET /. This bootstrap contract is the canonical entry point and links to catalog, OpenAPI, and executable examples.
Auth lanes
- Management lane: RFC 9421 `Signature-Input` + `Signature` (and `Content-Digest` for write operations).
- Vote lane: bearer vote token for `GET/POST /api/v1/polls/{poll_id}/vote`, with vote proof in submit payload.
Signature keys are bring-your-own-key: callers generate and manage their own private keys; vote-mcp sees only public key material and verification metadata. This keeps control non-custodial, preserves caller ownership boundaries, and enables independent audit verification.
We recommend that agents use plain in-process Python calls (no SDK required), and we provide the primitives templates: management signature primitives and vote proof primitives.
Vote signature and key management
To vote, a voter needs a vote link token and a private key.
The private key is used to sign the vote submission.
When the poll creator "mints" the vote link, they must provide the matching public key
(proof_public_key).
Our server uses that public key to verify the vote signature.
The private key stays with the caller and is never sent to our server.
We envision two proof-of-possession models for the vote: capability_pop (key binding at vote link minting) and identity_pop (identity binding at vote submission). In the current API version, only capability_pop is implemented.
- Shared group capability: one key/link package is shared by multiple voters.
- Per-voter (or per-org) capability: creator mints separate key/link packages.
- Voter-supplied key at mint time: voter sends public key first, then creator mints link.
- Creator-managed identity registry: creator stores identity-to-key mapping and mints from it.
- Reusable stable key: same voter/org key is reused across links or polls.
- Ephemeral key per event: fresh keypair per link/poll for tighter compartmentalization.
- Delegated/custodial signing: bound key is controlled by org signer/HSM/signing service.
Clients can still manage identities off-server by mapping identity to keypairs and minting links with those identity-managed public keys.
Technical note: Vote submission is intentionally a two-step flow.
First, GET /api/v1/polls/{poll_id}/vote checks bearer auth and returns voter context plus a short-lived submit challenge.
Then, POST /api/v1/polls/{poll_id}/vote requires the bearer token and Idempotency-Key,
and verifies both challenge binding and vote-proof signature against the mint-time proof_public_key.
Demo and Postman
You are currently on the demo server. Use it to practice request signing, lifecycle transitions, and vote-lane flows.
Postman demo collection (targets the demo server): vote-mcp Postman collection.