Skip to main content

sentinel-proof-mcp: stop your agent from showing hallucinated answers

PyPI Python MCP registry No API key License: Apache-2.0

An MCP server that fact-checks an LLM answer against the documents it was written from, before the user sees it. Claude Desktop, Claude Code, Cursor, VS Code, Windsurf or any Model Context Protocol client gets one tool, verify_answer. The agent passes its retrieved passages and its draft; the tool checks that every number appears in the passage the sentence cites and that every citation points at a passage that supports it. Wrong citations are re-pointed, unsupported sentences are removed, and an answer that is mostly unsupported is refused with a reason. The agent then shows safe_text, not the draft.

Runs locally over stdio. No model call, no network, no API key, no GPU: the check is sentinel-proof, a deterministic grounding gate that takes microseconds, so it can run on every answer rather than a sample. Nothing you verify leaves your machine.

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

Or try the same check in your browser first; nothing you paste is uploaded.

Use it when:

  • your agent answers from files, a vector store or search results and sometimes makes up a price, date, limit or percentage that is not in them;
  • it cites the wrong source, so a user who clicks [2] reads a passage that says nothing of the kind;
  • you want the answer grounded or refused, not a faithfulness score you then have to threshold, and not a second model call that is itself a model;
  • you need a check that is the same every time, for a regulated domain (legal, finance, healthcare, HR policy) or for a test suite;
  • you want it inside the agent loop, so the model fixes its own answer before replying, instead of a dashboard that tells you afterwards.

Install

You need uv (pipx works too). Every client below launches the server on demand with uvx sentinel-proof-mcp; there is nothing else to install or configure.

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).

Windsurf: the same block in ~/.codeium/windsurf/mcp_config.json.

VS Code (Copilot agent mode): in .vscode/mcp.json the key is servers:

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

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.

Python, if you would rather run it from an environment you manage: pip install sentinel-proof-mcp, then the command is sentinel-proof-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. In Claude Desktop or Cursor you can also just say "verify that against the sources with sentinel-proof".

How it compares

Other ways to catch a hallucinated answer from inside an MCP agent, and where this one differs. None of these is wrong; they answer different questions.

Where it runs Needs What you get back Fixes the answer
sentinel-proof-mcp your machine nothing per-sentence verdict, safe_text, refusal with reason yes: re-points citations, drops unsupported sentences
Ask the model to check itself the model a second model call an opinion, different each run sometimes, unverifiably
Hosted NLI / "verify" servers a vendor's API API key, your text uploaded a score or label per claim no
URL fact-checkers the web network whether a page says X no; and your passages are not URLs
RAG evaluation frameworks your CI a judge model faithfulness scores over a dataset no; offline

The trade: this check is lexical and numeric, not semantic. It catches the invented figure and the citation to the wrong passage, which are the hallucinations users notice and screenshot. It does not catch a paraphrase that misstates its source using the source's own words; for that, put a judge model behind it. It is the deterministic floor, not the ceiling.

FAQ

Does it need an API key or send my documents anywhere? No. The server is a local process over stdio, the check is pure Python with no dependencies, and it makes no network calls. The passages and the answer stay in the process.

Which clients does it work with? Any MCP client. It speaks stdio, the transport Claude Code, Claude Desktop, Cursor, VS Code and Windsurf use to launch local servers, and the test suite drives it that way as a real subprocess. Agent frameworks that speak MCP (the OpenAI Agents SDK, LangGraph, Pydantic AI, Semantic Kernel, n8n) can mount it the same way.

How is this different from asking Claude to double-check its answer? The model checking itself is another model call: it costs tokens, takes seconds, and gives a different answer each time. This tool is a rule: a number is in the cited passage or it is not. It returns the same verdict every run, in microseconds, and tells the model exactly which sentence failed and why.

My agent does not cite. Will it still work? Not yet: with nothing cited there is nothing to check, and the tool says so (ok: false, "No citations could be parsed"). Attach the cite_for_verification prompt to the drafting step, or add "cite each sentence as [n]" to your system prompt. Citation is what makes the answer checkable.

What counts as a passage? Whatever the model saw: chunks from a vector store, paragraphs from a file, search snippets, tool results. Pass them in the order the model saw them so that [1] means the first. Objects with id, source, section and page let the verdict say which document a sentence came from.

Does it work in languages other than English? Numbers are checked in any language. The word-overlap rule uses an English stop-word list, so for other languages it is stricter than intended; multilingual stop-words are on the roadmap of sentinel-proof.

Is there a version I can call from Python without MCP? sentinel-proof is the library; verify(answer, passages) is the same check. This package only puts it behind an MCP tool.

Where is it listed? In the official MCP registry as io.github.92kareeem/sentinel-proof, and on PyPI.

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.1

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.1
File Size Uploaded Provenance Actions
sentinel_proof_mcp-0.1.1.tar.gz 21.5 kB With provenance Details for sentinel_proof_mcp-0.1.1.tar.gz

Built distribution (wheel)

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

Total release size: 37.3 kB

Release files / sentinel_proof_mcp-0.1.1.tar.gz

Download URL sentinel_proof_mcp-0.1.1.tar.gz
Size 21.5 kB
Tags Source
SHA-256 checksum
How to use checksums
288f40ad504a60a4017f397841ed14f2bc63ecffb102f61e56c86117cd5eea88
BLAKE2b-256 checksum
How to use checksums
85c2c0f2f3434765c14970b6b35f1a27df6eed86c4e5d8fa11f3dfe81671eb12
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.1-py3-none-any.whl

Download URL sentinel_proof_mcp-0.1.1-py3-none-any.whl
Size 15.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
219e87ab62ec320193dd3dec7828490c22908791d9543f54045e8b762597c34b
BLAKE2b-256 checksum
How to use checksums
0d44ec616a96d382aa4ee00feca6312d66c2bce8ac45e921600a9e7bc1d4484b
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.1

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.1.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.1 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