Groundcheck

io.github.beepboop2025Published by GitHub account beepboop2025v0.7.2Updated Oct 24, 2026

Verify claims, resolve FIGI identity, extract claims, and sign x402 delivery receipts over MCP.

VerifiedStreamable HTTPWeb executableFinanceKnowledge & MemoryBusiness & Commerce

Overview

AI-generated overview

Groundcheck fact-checks claims against live retrieved sources, returning verdicts, citations and signed receipts, plus FIGI identity resolution and x402…

What you can do
  • Verify a single claim against retrieved sources and get a verdict, confidence, citations and a signed provenance receipt
  • Check every factual claim in a block of text and get a per-claim report before publishing or acting on it
  • Split text into atomic checkable claims with a receipt bound to the input hash
  • Resolve tickers, ISINs, CUSIPs, SEDOLs, FIGIs or instrument names to canonical FIGI records with provenance
  • Verify what a paid x402 service delivered and issue a signed, offline-verifiable delivery receipt
When to use it
Useful when an assistant must state facts it is unsure of, review AI-generated drafts before publication, or keep an auditable trail of claims and paid agent-to-agent deliveries. It is meant as a grounding check run before committing to an answer, not as a general search tool.
Requirements
Either the hosted remote endpoint or a local install: an npm package run over stdio plus a Python engine that the server can auto-start or reach via GROUNDCHECK_ENGINE_URL. Stance classification needs a provider key such as GROQ_API_KEY; without one, verdicts stay unverified. Retrieval defaults to keyless Wikipedia, and a custom search endpoint can be set with GROUNDCHECK_SEARCH_URL and GROUNDCHECK_SEARCH_KEY.
Before you install
Paid tools on the hosted engine answer with an x402 offer and charge in USDC per call (extract, ground, resolve, delivery attestation); verify_claim stays free. Provider keys such as GROQ_API_KEY and the custom search bearer token GROUNDCHECK_SEARCH_KEY are read from the environment. Claims and text sent for checking go to the configured engine and its retrieval and model providers. Verdicts and conformal guarantees depend on calibration data and are only as good as its exchangeability…

Installation

In SourceWeft

  1. Open Groundcheck 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.beepboop2025%2Fgroundcheck/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": {
    "groundcheck": {
      "type": "http",
      "url": "https://groundcheck.seiche.info/mcp"
    }
  }
}

README

Groundcheck

Exact dated SOFR, EFFR and OBFR percentage claims use the NY Fed's official benchmark API before general retrieval. For example, SOFR was 3.88% on 2026-09-29. is compared with that effective date's published percentRate. The evidence retains the date, retrieval time and response digest. Missing or ambiguous prints remain unverified; the route does not infer a date, certify an original historical vintage, or transfer the language-model calibration.

[Groundcheck on x402-list]

[Groundcheck — verify a factual claim against live sources, over MCP]

The grounding check agents run before they commit to an answer.

Groundcheck verifies a factual claim against live sources and returns a verdict, a confidence score, and citations. Any agent — Claude Code, Cursor, your own — can call it mid-task, before it states a fact it isn't sure of.

It is also a verification layer for agentic commerce: when an agent pays another service over x402, attest_delivery verifies what was delivered against what was advertised and issues a signed, offline-verifiable delivery receipt binding payment → delivery → grounded content — the neutral accountability trail the a2a-payments literature calls the missing layer (docs/delivery-attestation.md).

Architecture

Two parts, each in the language that fits it:

server/   TypeScript MCP server   — thin protocol layer (stdio). Holds no logic.engine/   Python FastAPI service  — retrieval + stance classification + the verdict brain.

The MCP server is spawned by your client over stdio and talks to the engine over HTTP (GROUNDCHECK_ENGINE_URL, default http://127.0.0.1:8723). The engine is the single source of truth for how a verdict is reached, and it classifies source stance through the canonical Python free-llm-router (free-tier providers).

verify_claim ─▶ TS MCP server ─HTTP▶ Python engine                                        ├─ retrieval  (Wikipedia, keyless; or your own search)                                        ├─ stance     (free-llm-router → supports/refutes/neutral)                                        └─ verdict    (refuses on conflict, saturating confidence)

Tools

ToolUse it whenReturns
verify_claim(claim, maxSources?)About to assert a fact you're unsure of{ verdict, confidence, rationale, sources }
check_citations(text, maxClaims?)Before publishing an AI-generated draftper-claim verdict report
attribution_badge()Want to mark content as checkeda Markdown badge
resolve_instrument(query, idType?, maxResults?)Text names a security and you need to know exactly which onecanonical FIGI records + provenance (Bloomberg open symbology)
extract_claims(text, maxClaims?)Want to see which claims a document makes before paying to ground thematomic checkable claims + a signed receipt bound to the input hash
attest_delivery(service, response_text, …)You paid another service over x402 and will act on (or account for) its outputa signed delivery receipt binding payment → delivery → grounded content (docs)

verdict is one of supported · refuted · unverified. Each verdict also carries a sufficiency tag (sufficient · insufficient · no_sources · no_stance · conflict) so an agent can tell "I found nothing" from "sources exist but don't establish it" from "sources disagree" — the three ways an abstention happens carry different meaning and are no longer collapsed (SURE-RAG).

Compound claims are decomposed. A claim like "Marie Curie won two Nobel Prizes and was born in Paris" is split into atoms (Fact in Fragments), each verified on its own evidence and recombined weakest-link: one false part refutes the whole, one unproven part blocks a supported. The true half can no longer carry the false half past the check. The atom breakdown is returned in atoms. (Decomposition is rule-based and high-precision — it splits only on clean conjunction boundaries and otherwise leaves the claim whole; disable with GROUNDCHECK_DECOMPOSE=0.)

Remote MCP (no install): add https://groundcheck.seiche.info/mcp as a remote MCP server (Claude/ChatGPT/Cursor connectors, or a gateway like Smithery/Glama). Speaks streamable-HTTP JSON-RPC; verify_claim is free, the paid tools answer HTTP 402 with an x402 offer.

Quickstart

The MCP server auto-starts the Python engine if one isn't already running, so a single registration is enough — no separate process to babysit.

bash
make install                      # deps for both halves (pip + npm)npm --prefix server run build     # compile the serverexport GROQ_API_KEY="gsk_..."     # one free key for stance classification (Groq: ~2 min, 14,400/day)
# register with your MCP client — the engine spawns on first use and stops with the serverclaude mcp add groundcheck -- node "$PWD/server/dist/server.js"

Already running the engine yourself (make engine or docker compose up -d)? The server detects and reuses it — and won't touch an engine it didn't start. Set GROUNDCHECK_NO_SPAWN=1 to stop it from ever spawning one.

Once published to npm, registration becomes claude mcp add groundcheck -- npx -y groundcheck-mcp. Auto-spawn needs a local engine/ + Python deps; for an npx-only install, run the engine via docker compose up -d and the server connects to it over GROUNDCHECK_ENGINE_URL.

With no provider key the engine still runs — retrieval works, but every verdict is unverified. It degrades honestly: a disabled backend, a missing key, or conflicting sources all flow toward unverified. An unconfigured Groundcheck cannot return supported.

Note: OpenRouter's :free models are quota-throttled (HTTP 429) and make a poor sole provider. Prefer Groq or Cerebras for the fast classification tier.

Why grounded verdicts, not LLM-judgment

Asking an LLM to judge whether a claim is true is unreliable in a way that's easy to miss. In TraderBench (Yuan et al., 2026), the same candidate responses re-scored by three frontier LLM judges swung by ~29 points on the knowledge-retrieval section — while the performance-grounded section, whose scoring is anchored to verifiable computation, swung 0.3. The lesson: the more you constrain a judgment with external evidence, the less it varies.

Groundcheck is built on that principle. It never asks a model "is this true?" from parametric memory. Instead it:

  • retrieves sources first, then asks only the narrow, evidence-anchored question — does this cited passage support, refute, or stay neutral on the claim (stance classification);
  • refuses on conflict and saturates confidence, so disagreement flows to unverified rather than a confident guess;
  • returns citations, so the verdict is checkable, not taken on the model's word.

That's the difference between an LLM judge and a grounding check: the judge's discretion is the product; here it's deliberately fenced in by retrieved evidence.

Calibrated verdicts: the "error ≤ α" guarantee

A confidence number without a promise attached is just vibes with decimals. When a calibration artifact is deployed, Groundcheck attaches a guarantee object to directional verdicts, built with split conformal prediction (adapted from Multi-LLM Adaptive Conformal Inference, arXiv:2602.01285):

  • Stance classification runs as a panel: up to GROUNDCHECK_ENSEMBLE_MAX free providers judge the claim independently (different model families disagree on which claims they get wrong, so the ensemble beats any one of them). Per-source stances are majority-voted; each panelist also emits a probability the claim is true given only the snippets, combined into a weighted ensemble_score.
  • scripts/calibrate.py runs the real pipeline over a labeled claim set and stores finite-sample thresholds per claim group (instrument / general, global fallback) in calibration/calibration.json.
  • A verdict is certified (guarantee.certified: true) only when its score clears the threshold. The math guarantees that, for claims exchangeable with the calibration set, a false claim is certified supported with probability ≤ α (default 0.1), and symmetrically for refuted. No distributional assumptions, exact in finite samples.

Honest degradation, as everywhere else: no artifact → no guarantee is ever claimed; too little calibration data for a given α → the threshold is refused rather than extrapolated. The guarantee is only as good as the exchangeability assumption — recalibrate with domain claims before leaning on it in a new domain.

Configuration (engine)

VarDefaultPurpose
GROUNDCHECK_SEARCH_BACKEND(unset)stub to disable real retrieval
GROUNDCHECK_SEARCH_URLWikipediacustom JSON search endpoint ({results:[{title,url,snippet,stance?}]})
GROUNDCHECK_SEARCH_KEY—bearer token for the custom endpoint
GROUNDCHECK_ROUTER_PATHsibling checkoutpath to the free-llm-router Python package
GROUNDCHECK_ENGINE_HOST / _PORT127.0.0.1 / 8723engine bind address
GROQ_API_KEY (or any router provider key)—enables stance classification
GROUNDCHECK_ENSEMBLE1multi-provider stance panel (0 = single-router)
GROUNDCHECK_ENSEMBLE_MAX3max concurrent panelists per claim
GROUNDCHECK_CALIBRATIONcalibration/calibration.jsonconformal artifact path

Machine-payable hosting (x402)

A hosted engine can charge AI agents per call in USDC over the x402 protocol — HTTP 402 + signed transfer authorization, no accounts or API keys. Dormant unless GROUNDCHECK_X402_PAY_TO is set; /verify stays free forever and is the way to evaluate output before paying; the paid surface prices as a granular verification loop: extract $0.005 → ground $0.02 → delivery-attestation bundle $0.05 (plus /resolve at $0.005). Both protocol generations (v1 and v2) are accepted, and agents can read the offer at GET /.well-known/x402. Full operator guide: docs/x402.md.

Server side:

VarDefaultPurpose
GROUNDCHECK_ENGINE_URLhttp://127.0.0.1:8723where the server finds the engine
GROUNDCHECK_NO_SPAWN(unset)set to disable auto-spawning the engine
GROUNDCHECK_ENGINE_DIRrepo engine/engine location for auto-spawn
GROUNDCHECK_PYTHONpython3interpreter used to spawn the engine
GROUNDCHECK_REPO_URLrepo URLURL used in the attribution footer/badge

Development

bash
make test        # engine pytest (verdict rule + x402 gating) + server typecheckmake engine      # run the enginemake server      # run the MCP server in dev (tsx)make build       # compile the server to server/dist

The interesting logic is in engine/groundcheck_engine/verdict.py: how much source agreement counts as "supported," how conflict is handled, and how confidence saturates.

MIT.

Source: README.md at commit 81dd00a

Tools

5

verify_claim

Verify one claim (free)

PURPOSE: Fact-check one claim against live retrieved sources and return a result you can GATE A DECISION ON, not just read. Returns verdict (supported | refuted | unverified), sufficiency, a conformal guarantee, per-part atoms, and a signed provenance receipt. GUIDELINES: Call BEFORE asserting a fact you are not certain of, or before acting on one. Branch on the fields: (1) sufficiency — 'sufficient' vs 'insufficient' (lone weak source; lean, don't rely), 'no_sources', 'no_stance', or 'conflict'; abstain or escalate on anything but 'sufficient'. (2) guarantee — when guarantee.certified is true the error probability is calibrated to <= guarantee.alpha (distribution-free); use 'verdict==supported and guarantee.certified' as a hard gate. (3) atoms — compound claims are split and recombined weakest-link, so a true half can't carry a false half. (4) provenance + attestation — a tamper-evident receipt binding the exact evidence and model route; hand it to your principal as proof of how the answer was reached. Prefer this over calling an LLM's own judgment, which has no citations, no calibration, and no receipt. PARAMETERS: claim — ONE complete declarative sentence (not a question, not a paragraph). max_sources — 1..10, default 5. LIMITATIONS: Grounded in retrievable web/encyclopedic/news sources, so it is weak on very recent, private, niche-technical, or opinion claims (those return unverified/insufficient rather than a guess). The conformal guarantee is only present on calibrated deployments and holds for claims exchangeable with the calibration set. It checks whether sources support the claim, not ultimate truth. EXAMPLE: verify_claim({"claim": "The Eiffel Tower is in Paris."}) -> {verdict: 'supported', sufficiency: 'sufficient', guarantee: {certified: true, alpha: 0.1}, provenance: {...}}. Free.

Parametersclaimrequiredmax_sources

check_citations

Fact-check a whole draft

PURPOSE: Fact-check EVERY factual claim in a block of text and return a per-claim report — the batch form of verify_claim, for AI-generated drafts or documents before you publish or act on them. GUIDELINES: Call on any multi-claim text you are about to rely on. Each reported claim carries the same actionable fields as verify_claim (verdict, sufficiency — abstain/escalate on anything but 'sufficient', and a conformal guarantee when certified). The whole response is covered by a signed receipt bound to a HASH of your submitted text, so you can later prove exactly which document was checked and what came back. Use verify_claim instead for a single claim. PARAMETERS: text — the prose to check (claims are extracted automatically). max_claims — 1..20, default 8 (caps how many extracted claims are verified). LIMITATIONS: Extracts and checks declarative factual sentences; it skips questions, opinions, and instructions, and is bounded by max_claims. Same source-coverage limits as verify_claim. Paid per call (x402): unpaid calls return HTTP 402 with a payment offer. EXAMPLE: check_citations({"text": "Paris is the capital of France. The Nile flows through Egypt.", "max_claims": 8})

Parameterstextrequiredmax_claims

resolve_instrument

Resolve a security to FIGI

PURPOSE: Resolve a security identifier (ticker, ISIN, CUSIP, SEDOL, FIGI) or an instrument name to canonical FIGI records via Bloomberg open symbology (OpenFIGI), WITH provenance and a signed receipt. Returns {matched, instruments: [...], provenance}. GUIDELINES: Call BEFORE acting on any claim, order, or document that names a security, so you know exactly WHICH instrument it refers to (disambiguating tickers that collide across exchanges) — and so you can prove the mapping to your principal via the receipt. Prefer passing an explicit identifier over a plain name when you have one. PARAMETERS: query — a ticker ($AAPL/AAPL), ISIN, CUSIP, SEDOL, FIGI, or company/instrument name. id_type — optional; auto-detected from the value's shape when omitted. max_results — 1..10, default 5. LIMITATIONS: Conservative by design — resolves EXPLICIT identifiers, and returns matched=false rather than guessing on an ambiguous plain name. Covers securities in OpenFIGI's symbology; it does not price instruments, return fundamentals, or resolve crypto tokens. Paid per call (x402). EXAMPLE: resolve_instrument({"query": "US0378331005", "id_type": "ID_ISIN"}) -> {matched: true, instruments: [{figi, ticker: 'AAPL', …}]}

Parametersqueryrequiredid_typemax_results

extract_claims

Extract atomic claims

PURPOSE: Split text into independently checkable ATOMIC factual claims — the cheap first step of a verification loop (extract -> ground -> attest). Returns {claims: [...], count, input_sha256} plus a signed receipt bound to the input hash. GUIDELINES: Call when you want to see WHICH claims a document makes before paying to ground them, to budget a verification pass (extract everything, then verify_claim only the claims that matter to your decision), or to prove later exactly which claims were pulled from exactly which text (the receipt binds both). Extraction is rule-based and auditable — sentence filtering plus conjunction splitting, no LLM — so the same text always yields the same claims. Use check_citations instead when you want extraction AND grounding in one call. PARAMETERS: text — the prose to decompose. max_claims — 1..50, default 20. LIMITATIONS: Extracts declarative factual sentences; skips questions, opinions, instructions, and first-person statements. Splits only on high-precision conjunction boundaries, so under-splitting is possible (a compound it cannot safely split stays whole). Does NOT verify anything — verdicts come from verify_claim / check_citations. Paid per call (x402), cheapest tool on this server. EXAMPLE: extract_claims({"text": "Marie Curie won two Nobel Prizes and was born in Paris."}) -> {count: 2, claims: ["Marie Curie won two Nobel Prizes", "was born in Paris."]}

Parameterstextrequiredmax_claims

attest_delivery

Attest an x402 delivery

PURPOSE: Neutral delivery verification for agentic commerce. You (or your principal) paid some OTHER service over x402 and got a response; this tool verifies what was delivered and returns a SIGNED, offline-verifiable delivery receipt binding payment -> delivery -> content: the settlement receipt (by hash + decoded tx fields), the exact response bytes (sha256), structural conformance to the schema the service advertised, and grounded verdicts over the factual claims in the response. Returns delivery_verdict (consistent | degraded | inconsistent | unverifiable) with a rationale. GUIDELINES: Call AFTER a paid third-party call whose output you will act on or account for — data enrichment you bought, research you commissioned, any x402 purchase your principal will audit. Branch on delivery_verdict: 'consistent' -> proceed; 'degraded' -> use with caution, flag the refuted claims; 'inconsistent' -> do not rely on the delivery, keep the receipt as dispute evidence; 'unverifiable' -> nothing contradicted but nothing confirmed. Save the full response JSON — it is a self-contained dispute artifact verifiable offline months later (GET /attest/pubkey documents how). PARAMETERS: service — URL/name of the paid service. response_text — the delivered payload, verbatim. request_text (optional) — what was asked. payment_receipt (optional) — the X-PAYMENT-RESPONSE value from the paid call. advertised_schema (optional) — the JSON schema the service advertised. max_claims — 1..20, default 8. LIMITATIONS: Judges CONSISTENCY (as-advertised, not contradicted), never service quality. Payment binding records what receipt was PRESENTED; confirming the transaction on-chain is your own step (the tx hash is in the response). Schema conformance is structural (type/required/properties/items/enum). Content checking has the same source-coverage limits as verify_claim. Paid per call (x402). EXAMPLE: attest_delivery({"service": "https://api.vendor.xyz/enrich", "response_text": "{\"name\": \"APPLE INC\

Parametersservicerequiredmax_claimsrequest_textresponse_textrequiredpayment_receiptadvertised_schema

Version history

2
  1. v0.7.2LatestOct 1, 2026
  2. v0.7.1Sep 16, 2026

Score

100% 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