Skip to main content

sentinel-proof-mcp: a hallucination check your agent can call

PyPI Python License: Apache-2.0

An MCP server that lets Claude Desktop, Claude Code, Cursor or any MCP client check a drafted answer against the sources it was written from before showing it. Every number must appear in the passage the sentence cites; a sentence whose citation is wrong is re-pointed to the passage that supports it; a sentence no passage supports is removed; an answer that is mostly unsupported is refused with a reason. Then the agent shows safe_text, not the draft.

It runs locally, makes no model or network calls and needs no API key. The check is sentinel-proof, the deterministic grounding gate; this package only puts it behind one MCP tool. Try the same check in the browser at the playground.

Install

You need uv (or pipx). The clients below launch the server on demand with uvx; nothing else to install.

Claude Code

claude mcp add --scope user sentinel-proof -- uvx sentinel-proof-mcp

Claude Desktop: Settings → Developer → Edit Config, then add to claude_desktop_config.json:

{
  "mcpServers": {
    "sentinel-proof": {
      "command": "uvx",
      "args": ["sentinel-proof-mcp"]
    }
  }
}

Cursor: the same block in .cursor/mcp.json (project) or ~/.cursor/mcp.json (global).

Any other client: the command is uvx sentinel-proof-mcp over stdio. For HTTP, uvx sentinel-proof-mcp --transport streamable-http --port 8765 serves http://127.0.0.1:8765/mcp.

What the agent gets

One tool, verify_answer:

Argument
answer the draft, with citations
passages the retrieved texts in the order the model saw them: strings, or {"text", "id", "source", "section", "page"}
question optional; figures the user typed are not counted as fabrications
citation_style "numeric" (default): [1], [2, 3] are 1-based positions in passages; "tag": [chunk:<id>]
max_stripped_ratio refuse when more than this fraction of claims is stripped (default 0.5)

It returns structured JSON: ok, safe_text (what to show), summary (one line telling the model what happened and what to do), claims (each sentence with supported / repaired / stripped, what it cited, what supports it, and any figures no passage contains), repaired_citations, stripped_ratio, refusal.

{
  "ok": true,
  "summary": "Verified: 2 of 3 claims supported. 1 citation(s) re-pointed to the right passage. 1 unsupported claim(s) removed. Show the user safe_text.",
  "safe_text": "Customers can get a refund within 30 days [1]. Requests above 500 USD need manager approval [2].",
  "claims": [
    {"text": "Customers can get a refund within 30 days", "status": "supported", "cited": ["p1"], "supported_by": ["p1"], "unsupported_numbers": []},
    {"text": "Requests above 500 USD need manager approval", "status": "repaired", "cited": ["p1"], "supported_by": ["p2"], "unsupported_numbers": []},
    {"text": "Refunds are processed in 2 business days", "status": "stripped", "cited": ["p2"], "supported_by": [], "unsupported_numbers": ["2"]}
  ],
  "repaired_citations": 1,
  "stripped_ratio": 0.333,
  "refusal": null
}

One prompt, cite_for_verification, which tells the model how to draft so that every sentence can be checked: cite each sentence as [n], copy figures exactly, reply INSUFFICIENT_CONTEXT when the sources do not answer. Use it as the system instruction of any answer-from-documents step, and the tool will have something to verify.

One resource, sentinel-proof://about, with the versions and the rules.

A typical turn

  1. The agent retrieves passages (its own search tool, a vector store, files).
  2. It drafts an answer with [1]-style citations (the prompt above).
  3. It calls verify_answer(answer, passages, question).
  4. It shows safe_text. If ok is false, summary says what was wrong: fabricated figures, no citations, or too little support, and what to do next (answer only from the passages, retrieve more, or tell the user).

The server's instructions say exactly this, so a client that reads them will do it without further prompting.

What it does not do

It checks evidence, not meaning: word overlap and numbers, no entailment model. A paraphrase that misstates its source and shares its vocabulary passes; an invented figure or a citation to the wrong passage does not. It is the deterministic floor under a judge model, not a replacement for one. Details and the design decision are in the sentinel-proof README.

Development

pip install -e ../sentinel-proof -e ".[dev]"
pytest -q            # in-process through the MCP client, plus one real stdio subprocess
ruff check . && mypy src

License

Apache-2.0.

Metadata

Release files for sentinel-proof-mcp 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sentinel-proof-mcp 0.1.0
File Size Uploaded Provenance Actions
sentinel_proof_mcp-0.1.0.tar.gz 17.0 kB With provenance Details for sentinel_proof_mcp-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for sentinel-proof-mcp 0.1.0
File Interpreter ABI Platform Actions
sentinel_proof_mcp-0.1.0-py3-none-any.whl Python 3 none any Details for sentinel_proof_mcp-0.1.0-py3-none-any.whl

Total release size: 30.7 kB

Release files / sentinel_proof_mcp-0.1.0.tar.gz

Download URL sentinel_proof_mcp-0.1.0.tar.gz
Size 17.0 kB
Tags Source
SHA-256 checksum
How to use checksums
848232b615ad2c0e94ff8e8aaa6925a84611be0559b9a06abba0980932fc5b23
BLAKE2b-256 checksum
How to use checksums
e27cab2316085eb175c06a0c77af1afc39ebe8cdc578f1b963f43b1db2b5d9d9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / sentinel_proof_mcp-0.1.0-py3-none-any.whl

Download URL sentinel_proof_mcp-0.1.0-py3-none-any.whl
Size 13.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e1f32dea30d52b3f678d026926b2af60b587095ec57ad7e259e6f72fda793719
BLAKE2b-256 checksum
How to use checksums
7454a9339a6a1015d4790a270f4ecd468b3911881168574b0bd1b7739ff6c54d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for sentinel-proof-mcp 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for sentinel_proof_mcp-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page