EVIDIQ Rubric MCP

EVIDIQ Rubric turns "is this deliverable acceptable?" into a deterministic, signed verdict against a spec both sides agreed on before the work started. Notary proves an output happened; Rubric decides whether it is acceptable — with a verdict anyone holding the same bytes can recompute.

Deterministic by construction: JSON Schema, normalised string and number matching, arithmetic re-checks, and a small declarative criteria language. No model in the hot path. Same input, same rule set, same spec → byte-identical verdict and digest.

What a Rubric report proves, and what it does not. Proves: this exact deliverable, under this spec version and this rule set version, produced these criterion results and this verdict; anyone with the same bytes recomputes the same digest. Does not prove: that the deliverable is correct, useful, or complete in a sense the spec did not encode. A PASS means the spec's criteria were met — no more.

Position in the family

Composition worth documenting: Rubric decides, Vault records the verdict, Notary timestamps the deliverable, Core scored the counterparty.

Related MCP server: stillos-notary-mcp

Status

Endpoints

All paths are served after Traefik strips /rubric. The container never sees the prefix, so the x402 challenge advertises PUBLIC_BASE_URL/mcp, never req.url (RUNBOOK §27-B).

Tools — five paid, five free

Prices are fixed atomic USD₮0 amounts and never read from an env var.

Paid

Free

The acceptance spec — a small declarative language

A spec is JSON. No expressions, no code, no regex the caller cannot see. It is versioned (specVersion: "1.0") and an unknown version is rejected rather than guessed at.

{
  "specVersion": "1.0",
  "deliverable": { "kind": "markdown" },
  "criteria": [
    { "id": "has-summary", "severity": "blocker",
      "type": "requiredSection", "section": "Summary", "minWords": 40 },
    { "id": "cites-sources", "severity": "blocker",
      "type": "minCitations", "count": 2 },
    { "id": "no-placeholder", "severity": "blocker",
      "type": "forbiddenPhrase", "phrases": ["TODO", "lorem ipsum", "as an AI"] },
    { "id": "length", "severity": "high",
      "type": "wordCount", "min": 300, "max": 1200 },
    { "id": "schema", "severity": "blocker",
      "type": "jsonSchema", "schemaRef": "#/schemas/report" },
    { "id": "numbers-grounded", "severity": "high",
      "type": "numbersGrounded", "tolerance": 0.001 }
  ]
}

Criterion types for v1, all deterministic:

• requiredSection — markdown heading by name; optional minWords for the section body.

• forbiddenPhrase — case-insensitive, smart-quote-folded; reports offsets and phrase indices, never text.

• wordCount — min / max inclusive.

• jsonSchema — bounded JSON Schema 2020-12 evaluation (see below).

• minCitations — distinct citation markers (e.g. [1], [Smith 2020], [unknown]).

• citationsResolve — each marker must resolve against a supplied source id.

• numbersGrounded — every numeric claim matched against sources within tolerance.

• dateSanity — dates fall within an optional windowStart/windowEnd window.

• requiredField — JSON Pointer (RFC 6901) path present in a JSON deliverable.

• enumValue — JSON Pointer field value is in an allowed set.

• uniqueBy — a JSON array has distinct values at a JSON Pointer field.

• arithmeticConsistent — sumField sums to targetField across rows.

Verdict rules, fixed and documented:

• any failing blocker → BLOCK

• no blocker, any failing high → REVIEW

• everything passes → PASS

• a criterion that cannot be evaluated (unparseable input, missing source) is INCONCLUSIVE, reported, excluded from PASS, and forces at least REVIEW.

• empty deliverable, empty criteria, every criterion INCONCLUSIVE → REFUSED (a verdict about nothing is the worst answer the service can give).

Grounding without a model

verify_grounding extracts quoted spans, numerals with units, percentages, dates, and citation markers from the deliverable, and looks for support in the supplied sources using, in order: exact match; whitespace- and case-normalised match; unicode-NFC and smart-quote-folded match; and for numbers, value equality within a stated tolerance after unit normalisation.

What it reports: supported with the source id and offset, unsupported with the offset in the deliverable, or inconclusive with a reason. What it never does: decide whether an unsupported sentence is false. Absence of support is not evidence of falsehood, and the report says so in those words.

Findings carry offsets and kinds, never the matched text for anything that could be sensitive — a report gets pasted into tickets.

Bounded JSON Schema evaluation (§8.4)

check_schema and the jsonSchema criterion use AJV (draft 2020-12) under a strict wrapper:

• No remote $ref. A $ref starting with http(s):// is rejected.

• No $ref cycles. A visited set keyed by resolved ref catches cycles.

• Depth cap (default 32) and node cap (default 10 000) prevent exponential blowup on pathological schemas.

• A time budget (default 2 000 ms) bounds total evaluation. A timeout returns INCONCLUSIVE, never PASS.

Per-path violations report expected vs actual type, never the value, so a rejected {name: 123} against {name: {type: "string"}} reports expectedType: "string", actualType: "number" without echoing 123.

Integrity — deterministic digest + optional EIP-191

Every report carries an integrity block:

{
  "integrity": {
    "algorithm": "SHA-256",
    "digest": "<sha256 of canonical envelope>",
    "signature": "0x…",          // optional
    "signer": "0x…",             // optional
    "signed": false,             // present only when no signer is configured
    "note": "No signer configured; the digest matches but the origin cannot be attributed."
  }
}

The canonical envelope is property-order-stable JSON over engine, ruleSetVersion, deliverableDigest, specDigest, verdict, counts, criteria, limits. The same bytes produce the same digest, regardless of who signs. verify_rubric_report recomputes the digest and verifies the EIP-191 signature offline; an unsigned report gets a digest verdict plus "origin cannot be attributed" — never valid: true.

OKX Payment SDK — the official path

Rubric uses the official OKX Onchain OS Payment SDK (@okxweb3/x402-core + @okxweb3/x402-evm) against the OKX facilitator, reused from Sentinel/Atlas/Warden (RUNBOOK §23). The price reaches the SDK as an explicit USD₮0 atomic AssetAmount, so the quoted fee token always matches the token registered on the listing.

Perbehaviours, each of which has its own past rejection (RUNBOOK §0.13, §29-A):

• HEAD /mcp → 402, immediately.

• Empty unauthenticated POST /mcp → 402 with a challenge. Never 400.

• The challenge resource.url comes from PUBLIC_BASE_URL, never req.url.

• Prices reach the SDK as USD₮0 atomic amounts.

• A facilitator success without a transaction hash is honoured with a [x402] SETTLED WITHOUT TX warning; pending/timeout without a hash fails.

• A malformed payment envelope is refused locally (~75 ms), never forwarded.

• Free tools answer without any payment header, always.

Hard safety rules (PLAIN §8)

1. A credential in the input (private key, mnemonic, API key by issuer shape) → refused, and nothing is stored, attested, or anchored.

2. Never echo deliverable content or source text in findings. Offsets, kinds, counts.

3. No network fetching of sources in v1. Sources are supplied inline. A URL in a spec is rejected with a reason, not fetched.

4. jsonSchema evaluation is bounded: no remote $ref, no $ref cycles, depth and node caps, and a time budget.

5. Artifacts live in memory with a short TTL, addressed by digest. Nothing is written to disk.

Limits

Pricing

• Per paid tool call: atomic USD₮0 amounts as listed above, on X Layer (eip155:196, chain 196).

• Token: USDT0 (0x779ded0c9e1022225f8e0630b35a9b54be713736, 6 decimals).

• EIP-712 token domain: { name: "USD₮0", version: "1" }.

• Free tools are always HTTP 200 and never gated.

Security boundaries

• The signer key is read from RUBRIC_SIGNER_PRIVATE_KEY and is the ONLY way reports get signed. There is no fallback key in the source. With no signer configured, the service runs unsigned and attest_acceptance refuses — an unsigned attestation would attest to nothing.

• The 0G anchor key is OG_PRIVATE_KEY, used to anchor digests only, never payloads. 0G failure is best-effort: never fatal to a paid call (the caller already paid; the local content-addressed artifact remains verifiable).

• The OKX SDK credentials (OKX_API_KEY/SECRET_KEY/PASSPHRASE) are the ONLY path to verification and settlement when present. A partial credential set throws at startup — never silently downgrades to a non-SDK path.

• The settle key (X402_SETTLE_KEY) is the legacy self-hosted settlement path. It is bypassed when OKX SDK credentials are present.

Quickstart

# Free: capabilities and pricing discovery
curl https://mcp.evidiq.dev/rubric/x402 | python3 -m json.tool

# Free: validate a spec before paying
curl -X POST https://mcp.evidiq.dev/rubric/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"validate_spec","arguments":{"spec":{"specVersion":"1.0","deliverable":{"kind":"markdown"},"criteria":[{"id":"x","severity":"blocker","type":"wordCount","min":10}]}}}}'

# Paid: check_acceptance (402 without a PAYMENT-SIGNATURE envelope)
curl -X POST https://mcp.evidiq.dev/rubric/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"check_acceptance","arguments":{"deliverable":"# Summary\nThis deliverable meets the agreed spec.","spec":{"specVersion":"1.0","deliverable":{"kind":"markdown"},"criteria":[{"id":"has-summary","severity":"blocker","type":"requiredSection","section":"Summary","minWords":5}]}}}}'
# Expected: 402 with amount:"15000", x402Version:2, scheme:"exact"

Self-host

# 1. Install + build
npm ci && npm run build

# 2. Run with no payment env → all tools free (honest downgrade)
PORT=3100 npm start

# 3. Verify
curl -s localhost:3100/health
curl -sX POST localhost:3100/mcp -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# 4. Add OKX SDK credentials + RUBRIC_SIGNER_PRIVATE_KEY to enable the paid path
PORT=3100 OKX_API_KEY=… OKX_SECRET_KEY=… OKX_PASSPHRASE=… \
  X402_PAY_TO=0x2a8efe3093278bb4bd3b2d9c7b5ba992ca4fc9b0 \
  PUBLIC_BASE_URL=http://localhost:3100 \
  RUBRIC_SIGNER_PRIVATE_KEY=… \
  npm start

Development

npm test            # vitest run — 118 tests
npm run build       # tsc -p tsconfig.json
npm run dev         # tsx watch start-server.ts

Configuration (/root/evidiq-rubric.env on the box; .env.example here)

See .env.example for the full list with names only (no values). Note in particular:

• Variable names are named after THIS service. A copy-pasted variable name is what put a public signing key in production once (RUBRIC_SIGNER_PRIVATE_KEY, never VAULT_SIGNER_PRIVATE_KEY).

• Every key is accepted with or without the 0x prefix — every deployment here stores bare hex.

• The passphrase contains #; keep it unquoted for docker --env-file.

Proven on-chain

The pre-submit gate (PLAN §13) requires one real paid call per paid tool at least once across the suite, with the receipt mining status 0x1, the container logging [x402] SETTLED with a hash, and the report signature tracing to the project signer (0x8a3c7524…ee7D, the family OG signer = RUBRIC_SIGNER_PRIVATE_KEY).

The broadcaster for every settled tx is the OKX official facilitator relayer (not our buyer, not our settle wallet) — which is what proves the SDK is the live settlement path (RUNBOOK §27-F).

Container logs show [x402] SETTLED for every paid tool name with its tx hash. The free verify_rubric_report tool was called immediately after each paid call on the report the service just produced; all five returned valid:true, digestMatch:true, signatureValid:true (§13 item 10).

Free tool valid-argument sweep (§13 item 3)

Every free tool called with genuinely valid arguments against the live endpoint returns a substantive, non-error result. Per-tool:

The bare-{} sweep (§13 item 2) and wrong-but-plausible sweep (§13 item 4) are covered by the test suite (118 passing). The capabilities diff (§13 item 6) is green: every name in tools/list appears in rubric_capabilities.

Hospitality for the OKX listing validator

onchainos payment quote https://mcp.evidiq.dev/rubric/mcp --method POST returns ok:true (§13 item 11). Quoted per-tool: check_schema 5000 (amountHuman:"0.005", tokenSymbol:"USD₮0", recipient: family 0x2a8efe30…). The SDK-path liveness check (§13 item 8) is also green: a malformed envelope is refused locally in ~85 ms; a well-formed envelope with a bad signature reaches the OKX facilitator and comes back rejected as invalid_signature in ~253 ms (RUNBOOK §29-A). Reproduce the live proofs with node paid-call-proof.mjs (default: check_schema; override with TOOL=verify_grounding node paid-call-proof.mjs, etc.). Full-suite spend across all five paid tools: about 0.08 USDT0 (the budget PLAN §13 set).

Architecture

HTTP (node:http) ── /health, /x402, /skill.md, /mcp (HEAD → 402)
                       │
                       ▼
                 withX402Gate ──── decodePaymentHeader ── verifyPaymentLocal (local preflight)
                       │                    │
                       │                    └── OkxSdkVerifier.verify + settle (official SDK)
                       │                           │
                       │                           └── poll getSettleStatus on pending/timeout
                       ▼
              rawHandler (JSON-RPC dispatch)
                       │
                       ▼
              createServer() — 5 paid tools + 5 free tools
                       │
                       ▼
       lib/rubric/ — spec, criteria (one fn per type), verdict, grounding,
                     schema (bounded AJV), report (canonical digest + EIP-191),
                     attest (EIP-191 + 0G anchor), artifacts (TTL cache),
                     secrets (credential refusal).

Links

• OKX Payment SDK: https://web3.okx.com/onchainos/dev-docs/payments/service-seller-sdk

• EVIDIQ runbook (local): EVIDIQ-RUNBOOK.md — §23 is the source of truth for payments.

• Skill document: served at https://mcp.evidiq.dev/rubric/skill.md.

License

MIT © 2026 EVIDIQ. See LICENSE.