sentinel-proof-mcp: a hallucination check your agent can call
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
- The agent retrieves passages (its own search tool, a vector store, files).
- It drafts an answer with
[1]-style citations (the prompt above). - It calls
verify_answer(answer, passages, question). - It shows
safe_text. Ifokis false,summarysays 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.