MCP server for groundlens — a deterministic first-stage grounding check for Claude Desktop, Cursor, Windsurf, and any MCP-compatible client. It checks whether an answer was drawn from its source, in milliseconds, with no model in the scoring path. Same inputs → same scores, every time.
It is a filter, not a judge. It has a characterized blind spot, and every check says so.
| Tool | Install |
|---|---|
| Cursor |  |
| VS Code |  |
| VS Code Insiders |  |
Adds three tools to your AI assistant:
| Tool | What it checks | When to use it |
|---|---|---|
groundlens_check |
Auto-selects the right method | Default — just use this one |
groundlens_sgi |
Response vs. source document (SGI) | RAG pipelines, document Q&A |
groundlens_dgi |
Response patterns without context (DGI) | Chat, general Q&A |
SGI (Semantic Grounding Index) measures whether the response engaged the source material or just rephrased the question. The default triage threshold is 0.95, and it is a starting point, not a verdict: calibrate it on your own grounded distribution. SGI sorts, it does not decide.
DGI (Directional Grounding Index) is the context-free fallback. It is the weakest signal here and it has a measured ceiling (see below). Prefer SGI whenever you have the source.
pip install groundlens-mcpOr with uv:
uv pip install groundlens-mcpClaude Code (CLI):
claude mcp add groundlens -- uvx groundlens-mcpClaude Desktop, Windsurf, Cline, or any MCP client — add to its config:
{ "mcpServers": { "groundlens": { "command": "uvx", "args": ["groundlens-mcp"] } } }Add to your claude_desktop_config.json:
-
macOS:
~/Library/Application Support/Claude/claude_desktop_config.json -
Windows:
%APPDATA%\Claude\claude_desktop_config.json -
Linux:
~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"groundlens": {
"command": "groundlens-mcp"
}
}
}If you installed with uv and the command isn't on your PATH:
{
"mcpServers": {
"groundlens": {
"command": "uv",
"args": ["run", "groundlens-mcp"]
}
}
}Add to .cursor/mcp.json in your project:
{
"mcpServers": {
"groundlens": {
"command": "groundlens-mcp"
}
}
}Example with Cursor:
- Cursor self-verification loop — drop-in
.cursor/config + rule that makes Cursor verify every answer with Groundlens.
Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"groundlens": {
"command": "groundlens-mcp"
}
}
}Once configured, ask your ai assistant:
"Check if this response is hallucinated"
"Is this answer grounded in the document I provided?"
"Did this ChatGPT answer actually come from the document I gave it?"
The tools return JSON with a plain-language CHECK check, a numeric score, and the raw components. The wording comes from groundlens.check — the same source of truth used by the library and docs, so it reads identically everywhere.
{
"check": "Not supported by the document",
"message": "The answer stays closer to the question than to the source, so it may not come from the document. Check it before trusting it.",
"headline": "CHECK: Not supported by the document (Semantic Grounding Index - SGI=0.87)",
"level": "risk",
"method": "Semantic Grounding Index",
"score": 0.87,
"flagged": true,
"detail": "distance to source 0.49, distance to question 0.43"
}The check level is ok / review / risk (from the calibrated thresholds). For context-free DGI checks the check reads Looks grounded / Partly grounded / Not grounded, plus a note that no source was provided.
Every response also carries escalate and handoff. Do not drop them. A passing check means the answer came from the source. It does not mean the facts are right, and handoff says so in plain language:
{
"check": "Supported by the document",
"level": "ok",
"escalate": false,
"handoff": "Grounding, not facts: a plausible wrong fact in the right frame would pass this check. Verify facts in a second stage."
}A client that renders the check without the handoff silently green-lights the one class of error this method provably cannot see.
groundlens uses embedding geometry, with no model in the scoring path, to check provenance: did this answer come from its source?
- SGI computes
dist(response, question) / dist(response, context). If the response moved toward the context, it engaged the source. If it stayed near the question, the context was likely ignored. - DGI projects the question→response displacement onto the mean direction of answers written from a source. Context-free, and coarse.
Both run a single embedding call. No inference. Deterministic.
Bin confabulations by how far they sit from the register of a correct answer, and every embedding-similarity method, this one included, declines toward chance as the answer moves into register: same vocabulary, same phrasing, one wrong number. At the in-register end classic encoders reach AUROC 0.62 to 0.68 and raw cosine 0.595. With authorship held constant the directional score reaches 0.606, and the ceiling of the whole class is about 0.68.
Entailment does not decline. Across the same bins an NLI cross-encoder holds 0.836, 0.786, 0.837, 0.719, 0.887, and it is strongest exactly where geometry is weakest. Entailment is the recommended second stage. This server runs first, on everything, for free, and hands over what it cannot settle.
Full write-up: The Register Wall: What Similarity-Based Hallucination Detectors Actually Measure (under review). Read it before relying on any similarity-based detector, including this one.
The first tool call downloads and loads the sentence-transformer model (~100MB). Subsequent calls are fast. The model is loaded lazily so your MCP client doesn't slow down on startup.
git clone https://github.com/groundlens-dev/groundlens-mcp.git
cd groundlens-mcp
pip install -e .
groundlens-mcpOr:
python -m groundlens_mcp- groundlens library —
pip install groundlens - Documentation
- Website
- Demo