io.github.stillmarcus24/stillos-notary-mcp

stillos-notary-mcp

Verification infrastructure for the agentic economy. An agent submits a claim; the notary returns an Ed25519-signed, hash-chained verdict, settled against real external ground truth, not model output. Free tier, no account, no card.

Every tool call in this package settles against the live public notary over HTTPS (stillosdigitalholdings.com/notary). No local or internal-only code path exists — behavior is identical regardless of runtime.

Install

npx stillos-notary-mcp mcp

Or add to an MCP client config:

{
  "mcpServers": {
    "stillos-notary": { "command": "npx", "args": ["-y", "stillos-notary-mcp", "mcp"] }
  }
}

Tools

claim_verdict

Submits a claim and a resolver specification. Returns CONFIRMED, REFUTED, or ERROR — never a forced guess — signed and hash-chained.

Supported resolver types: github_pr, onchain_tx, url_json, http_status, kalshi_market.

stillos-notary-mcp claim "your-agent" "example.com returns 200" \
  '{"type":"http_status","url":"https://example.com","expect_code":200}'

verify_receipt

Independently verifies any receipt by hash: confirms the hash chain is intact and the signature is valid.

stillos-notary-mcp verify <receipt_hash>

file_dispute

Files a bonded dispute against a verdict receipt. The disputed verdict is re-resolved immediately, against the identical resolver specification that produced it — independent re-run, not a re-vote, not a human appeal queue. An upheld dispute overturns the verdict and queues a slashable payout against the notary's on-chain correctness bond ($10 USDC, Base). Dispute window: 48 hours from the original receipt's timestamp.

Paying for a paid tool (1.3.0)

Through 1.2.2 this package could only report the paywall: every paid tool returned { payment_required: true } and the call ended there. There was no way, anywhere in the package, to attach a payment and retry — the CLI told you to "attach payment and retry" using a mechanism that did not exist. 1.3.0 implements it.

Supply a credential and the 402 is crossed automatically — one 402, one payment, one retry, then the paid result:

const { callTool } = require('stillos-notary-mcp');

// 1. Preferred: your own payment-capable fetch. We never see a key.
const r = await callTool('screen_entity', { agent: 'me', entity: 'Acme Corp' },
                         { fetch: myX402Fetch });

// 2. Or a viem account / signer object.
await callTool('screen_entity', args, { account: myViemAccount });

// 3. Or, as a documented fallback, a raw key in the environment.
//    export STILLOS_NOTARY_WALLET_KEY=0x...
await callTool('screen_entity', args);

With no credential you get an actionable requirement rather than a dead end:

{
  "ok": false, "paid": false, "code": "PAYMENT_REQUIRED",
  "payment": { "amount_usd": 0.001, "network": "base", "pay_to": "0x…", "scheme": "exact" },
  "remediation": "Pass a payment-capable fetch as opts.fetch, a viem account as opts.account, or set STILLOS_NOTARY_WALLET_KEY, then call again."
}

What it refuses to pay. A 402 is untrusted input. The client will not sign for a network or scheme it does not expect (base / exact only), will not pay a malformed requirement missing payTo or an amount, and will not exceed a per-call ceiling ($1.50 default, STILLOS_NOTARY_MAX_USD or opts.maxUsd to change). It never retries more than once — a second 402 is a hard stop, not a backoff loop, so a rejected payment can never be re-signed into a double spend. Supplying no credential never spends anything. No key is received, logged, persisted, or placed in an error message.

Covered by test/payment-continuation.test.cjs (17 cases, local mocks, no real settlement).

Paid: $1.00 USDC (Base) via x402 — no free tier. A call without an attached x402 payment returns the payment requirement (price, payTo, asset), not a verdict. This package holds no wallet and executes no payment itself; the calling agent's own client bears that capability.

stillos-notary-mcp dispute "your-agent" <receipt_hash>

screen_entity

OFAC SDN sanctions name screen, with a source_as_of freshness timestamp, Ed25519-signed.

Free up to 5/agent/day, then $0.001 USDC (Base) via x402.

stillos-notary-mcp screen "your-agent" "Acme Corp"

distress_score

Balance-sheet corporate distress ranker for a single equity ticker: Altman Z-score from live SEC XBRL filings, held-out AUC 0.769 on 178 real Chapter 11 filings vs 71 date-matched controls. ~3% precision at a 2% base rate: a ranking input for ordering a review queue, NOT an alarm on a single name. The prior "71% sensitivity / 100% specificity" claim (n=14) is withdrawn. Ed25519-signed.

Free up to 3/agent/day, then $0.15 USDC (Base) via x402.

stillos-notary-mcp distress "your-agent" AAPL

Why

Most verification is one model checking another model's output — the same failure mode, with no independence introduced. This architecture settles every claim against a source neither counterparty controls, signs the outcome regardless of direction, and publishes confirmed and refuted verdicts to the same ledger. Fail-closed: an unresolvable claim returns ERROR, never a plausible-sounding guess.

Live docs: https://stillosdigitalholdings.com/notary/docs