# mcp-verify-claim

A Model Context Protocol (MCP) server that forces **evidence-gated, honestly
tiered** claim reporting. Every claim an agent makes gets classified into an
evidence tier (**FACT / INFERENCE / SPECULATION / UNVERIFIED**) with attached
evidence — the antidote to the silent-unverified-claim failure mode
("pushed successfully", "the tests pass", "the API returned 200" — asserted
without ever running the command).

Deterministic, no LLM, no network calls. Self-hostable, MCP-compatible with
any agent (Claude Code, Cursor, Copilot, OpenClaw, Codex CLI).

## Why it exists

The most common agent failure is not wrong reasoning — it's reporting a
plausible-sounding *result that was never verified*. `mcp-verify-claim`
installs a hard gate: no unverified claim can be reported as fact.

## The pattern it fits (agent tooling that answers with evidence, not opinion)

When you give an agent access to real operations (edits, checks, rule
evaluation, mutations) through MCP, the value is that it can **answer with
evidence instead of opinion** — it ran the check, it saw the real state, it can
prove what it did. But that only holds if the agent is *forced* to attach the
evidence. A rules-and-checks surface ("is the module valid?", "did this state
change slice apply?", "what actually changed?") is exactly the high-value case:
each check produces a machine-verifiable result.

`mcp-verify-claim` is the gate that guarantees the agent reports the result with
its evidence attached (exit code, real read-back, actual HTTP status) and cannot
pass off a guess or an unrun step as truth. Pair it with any MCP surface that
exposes operations, and the agent's answers become auditable, line-by-line,
instead of plausible.

## Tools

- `tier_claim(claim, evidence, verification_kind)` — classify a claim into a
  tier + verdict (`TRUST` / `REVIEW` / `DO-NOT-REPORT`) + honest next-action.
- `check_claim(claim)` — deterministic scan for fabrication/hedging signals
  (completion-without-artifact, "the API returned", hedge words).
- `report_templates()` — the canonical STATUS / EVIDENCE / GAPS completion
  shape and the 6-step behavioral loop.
- `tier_definitions()` — the FACT / INFERENCE / SPECULATION / UNVERIFIED
  definitions.

## Evidence tier (the core)

| Tier | Meaning | Verdict |
|------|---------|---------|
| **FACT** | Saw it in raw tool output (exit code, body, file read-back, HTTP status) | TRUST |
| **INFERENCE** | Deduced from facts; show the chain | REVIEW |
| **SPECULATION** | A guess; never report as truth | REVIEW |
| **UNVERIFIED** | No evidence produced | DO-NOT-REPORT |

## Install & run

**One command (recommended) — installs from the repo, no PyPI token needed:**

```bash
uv tool install git+https://github.com/sudo-ai-git/mcp-verify-claim
mcp-verify-claim                         # run stdio server
mcp-verify-claim --http --port 8137      # or Streamable HTTP for remote use
```

Or with `pipx`: `pipx install git+https://github.com/sudo-ai-git/mcp-verify-claim`

**Direct from source (fallback):**

```bash
pip install mcp
python3 mcp_server.py
```

### Claude Desktop / agent config

```json
{ "mcpServers": {
    "verify-claim": { "command": "mcp-verify-claim", "args": [] }
}}
```
 
## Example

```text
tier_claim("Successfully deployed", evidence="", verification_kind="")
--> tier UNVERIFIED, verdict DO-NOT-REPORT
    signals: [high] completion claim without artifact
    next: go get the evidence before reporting

tier_claim("Deploy is live", evidence="origin/main SHA==local HEAD, HTTP 200", verification_kind="read_back")
--> tier FACT, verdict TRUST
```

## Part of a family

This is one of three **deterministic, no-LLM** agent-trust MCP servers by `sudo-ai-git`:

- [`mcp-skill-sec`](https://github.com/sudo-ai-git/mcp-skill-sec) — pre-install skill/security audit
- [`mcp-verify-claim`](https://github.com/sudo-ai-git/mcp-verify-claim) — evidence-gated, honestly-tiered claim reporting (this repo)
- [`mcp-benchmark-hygiene`](https://github.com/sudo-ai-git/mcp-benchmark-hygiene) — pytest config-leakage / eval-honesty detection

**Sibling product:** [`mcp-token-saver`](https://github.com/sudo-ai-git/mcp-token-saver) — token-cost proxy + analyzer for agent conversations (dedupes redundant tokens before they're billed; live-proven 74% cut). [Discussion](https://github.com/sudo-ai-git/mcp-token-saver/discussions/1)

**Also in the family** (a free CLI, not an MCP server): [`harness-audit`](https://github.com/sudo-ai-git/harness-audit) — deterministic agent-eval / benchmark-grading hygiene audit that catches the same silent config-leakage mis-scoring class. Free lead-magnet; the same verification discipline, zero dependencies, auditable line-by-line.

## License & provenance

MIT. Written by `sudo-ai-git`. Standalone behavioral-rigor tool; encodes no
proprietary method. MCP expression of the `verify-before-claim` agent skill.

## Official MCP Registry metadata

mcp-name: io.github.sudo-ai-git/mcp-verify-claim

## Hire a custom integration

Need this connected to *your* internal system (auth, logging, security-scan pass, hosted)? Open a [custom-build request](https://github.com/sudo-ai-git/agent-infra-builds/issues/new?template=custom-build-request.yml). MIT reference assets are free to use either way.