Skip to main content
Glama
groundlens-dev

groundlens-deprecated

Official
by groundlens-dev
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

Groundlens MCP

Python CI codecov License OpenSSF Scorecard OpenSSF Best Practices groundlens-mcp MCP server

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.

One-click install

Tool

Install

Cursor

Install in Cursor

VS Code

Install in VS Code

VS Code Insiders

Install in VS Code Insiders

Related MCP server: Arkheia Hallucination Detection MCP

What it does

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.

Install

pip install groundlens-mcp

Or with uv:

uv pip install groundlens-mcp

More clients

Claude Code (CLI):

claude mcp add groundlens -- uvx groundlens-mcp

Claude Desktop, Windsurf, Cline, or any MCP client — add to its config:

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

Configure your client

Claude Desktop

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"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "groundlens": {
      "command": "groundlens-mcp"
    }
  }
}

Example with Cursor:

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "groundlens": {
      "command": "groundlens-mcp"
    }
  }
}

How to use

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.

Example output

{
  "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.

What this does not do

This is a grounding check, not a fact check. Three specific things it cannot see:

  • Type III — a factual error inside the right frame. A wrong answer that keeps the vocabulary, structure and register of the correct one (right topic, right terminology, one wrong number or date) lands inside the plausibility region of the correct answer in embedding space, and is geometrically indistinguishable from it. This server will pass it. That is the whole reason the escalate and handoff fields exist — a passing check means the answer engaged its source, it does not mean the answer is right.

  • Anything a single frozen sentence embedding cannot express. The bound behind the ceiling below applies to detectors that are functions of one frozen sentence embedding. It says nothing about detectors that read activations, log-probs, multiple samples, or retrieval — and it does not license the claim that those cannot do better.

  • Truth, of any kind. Never render a passing check as "verified", "accurate" or "not hallucinated". Send what this cannot settle to a second stage: an entailment check, a lookup against the source, or a judge.

How it works

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.

The register wall, and why there is a second stage

Bin confabulations by how far they sit from the register of a correct answer, and a detector that is a function of a single frozen sentence embedding — 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. On the authorship-matched split the directional score (DGI) reaches 0.606, a logistic probe 0.660 and an MLP probe 0.675.

Three scope conditions, because the result is narrower than it is usually quoted:

  • The ~0.68 ceiling is measured for DGI and for logistic/MLP probes over those embeddings. It is not a demonstrated ceiling for every embedding-similarity method. Stronger classifiers (random forest, XGBoost) retain residual signal up to 0.88 at high register alignment.

  • Register sufficiency is an assumption, not a theorem, and it is only partially true: residual surface features retain a Spearman correlation of up to 0.37 after register alignment is controlled for.

  • The formal bound covers only detectors that are functions of a single frozen sentence embedding. It says nothing about detectors that read activations, log-probs, multiple samples, or retrieval.

SGI and DGI are also not interchangeable: SGI uses a source document, DGI is reference-free, and the authorship control was run on DGI and on probes over embeddings, not on SGI. Never quote a number for one as if it were the other.

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 Outer Geometry of Truth: Register Alignment and the Limits of Embedding-Based Hallucination Detection — this is the paper everything else refers to as "the register wall". Read it before relying on any similarity-based detector, including this one.

Paper status. arXiv preprints. Each has been through peer review at COLM, NeurIPS or ACL, three reviewers per paper, and each current version was revised to address every point raised. None is accepted at a venue yet. The Outer Geometry of Truth is newer than the others and has not been through that cycle.

First-call latency

The first tool call downloads and loads the default encoder, sentence-transformers/sentence-t5-large (335M parameters, 768 dims, ~670 MB of weights). On a normal connection that download takes a minute or two; it is cached afterwards and subsequent calls are fast. The model is loaded lazily so your MCP client doesn't slow down on startup.

To trade accuracy for size, pass a smaller encoder to the groundlens library (all-MiniLM-L6-v2 is 22M parameters, ~90 MB) — but the bundled SGI thresholds and the certified DGI reference direction were calibrated on sentence-t5-large, so any other encoder needs its own calibration before its flags mean anything.

Running from source

git clone https://github.com/groundlens-dev/groundlens-mcp.git
cd groundlens-mcp
pip install -e .
groundlens-mcp

Or:

python -m groundlens_mcp

Links

Available Tools

3 tools
groundlens_checkA
Read-onlyIdempotent

Check whether an LLM response was drawn from its source. Grounding, not truth.

This is the main tool. It automatically selects the right method:

  • If context is provided: uses SGI (Semantic Grounding Index) to check whether the response actually engaged the source material.

  • If no context: uses DGI (Directional Grounding Index), a coarse signal with a known ceiling.

Both are deterministic — same inputs always produce the same score. No model in the scoring path. Scoring is embedding geometry.

IMPORTANT — how to report the result. A passing check means the response ENGAGED ITS SOURCE. It does NOT mean the facts are correct. A plausible wrong fact stated in the right frame (right topic, right terminology, one wrong number or date) will pass. Do not tell the user a passing check means the answer is "verified", "accurate" or "not hallucinated". Always surface the handoff field, and when escalate is true, say so: the case needs a second stage (an entailment check, a lookup against the source, or a judge).

Args: params (CheckInput): The question, response, and optional context.

Returns: str: JSON with a plain-language CHECK (Supported / Partly supported / Not supported by the document, or Looks grounded / Partly grounded / Not grounded), score, level, method, message, escalate, handoff, and the raw components.

Examples: - "Did this ChatGPT answer actually come from our policy document?" → provide question + response + the policy document as context - "Did this answer engage its source at all?" → provide question + response (no context needed)

ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Disclosures beyond annotations include deterministic nature, no model in scoring path, and limitation that plausible wrong facts can pass. No contradiction with annotations (readOnlyHint, idempotentHint, etc.).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with sections, examples, and warnings. It is slightly lengthy but every sentence adds value. Front-loaded with core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (two methods, output with multiple fields) and available annotations/schema, the description provides complete guidance on behavior, limitations, and expected output. No output schema provided but output fields are explained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema descriptions cover individual fields (question, response, context), the description adds meaning about parameter behavior (auto-mode selection based on context presence) and output interpretation. The 0% schema coverage for the top-level params property is compensated by rich tool description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool checks grounding against a source and distinguishes itself from siblings (groundlens_dgi, groundlens_sgi) by being the main tool that auto-selects method. It clearly identifies the verbs 'check' and 'drawn from'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidance on when to use context (SGI) vs without (DGI), and warns about interpretation of results. Includes examples of appropriate use cases and alternative tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

groundlens_dgiA
Read-onlyIdempotent

Coarse context-free grounding signal, for when no source is available (DGI).

DGI (Directional Grounding Index) compares the question-to-response displacement against the direction typical of answers written from a source. No context is needed, so it works for open-ended chat and general Q&A.

IMPORTANT: this is the weakest signal here and it has a measured ceiling. With authorship held constant it reaches AUROC 0.606, and the ceiling of the entire embedding-similarity class is about 0.68. It is a ranking signal for triage, not a detector, and it is not a risk verdict. Prefer groundlens_sgi whenever a source is available. Never report a DGI score as evidence that an answer is true or false.

Args: params (DGIInput): The question and LLM response.

Returns: str: JSON with a plain-language CHECK, the DGI score, the magnitude, escalate and handoff.

Examples: - Ranking a batch of chat answers so a reviewer starts with the worst - Screening outputs when no source document exists

ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses limitations: 'weakest signal', measured AUROC ceiling 0.606, ranking signal, not detector. Adds behavioral context beyond annotations (readOnlyHint, idempotentHint).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with sections, front-loaded summary, and each sentence adds value. Slightly verbose but efficient overall.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers use cases, limitations, and return format. Output schema exists, so return details are optional. Given tool complexity, description is complete and appropriate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Description mentions 'params (DGIInput): The question and LLM response' but adds little beyond schema. Schema descriptions already cover parameters, so no major gap, but description doesn't compensate for low schema_description_coverage (0%).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'coarse context-free grounding signal' for when no source is available, and distinguishes it from sibling tools by recommending groundlens_sgi when a source exists.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use (no source available), when not to use ('Never report as evidence'), and suggests alternative (groundlens_sgi).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

groundlens_sgiA
Read-onlyIdempotent

Check whether an LLM response engaged a source document (SGI). Provenance, not truth.

SGI (Semantic Grounding Index) measures whether the response engaged with the provided context or stayed anchored to the question. This is the method to use for RAG pipeline verification — did the model actually use the retrieved documents?

The score is a ratio: dist(response, question) / dist(response, context). A high ratio means the response moved toward the context. A low ratio means it stayed near the question (possibly ignored the context).

IMPORTANT: this measures PROVENANCE. An answer that borrows the source's vocabulary and structure but changes one figure will pass. Surface the handoff field and escalate fact-level verification to a second stage.

Args: params (SGIInput): The question, source context, and LLM response.

Returns: str: JSON with a plain-language CHECK, the SGI score, and the two distances.

Examples: - Verifying a RAG chatbot used the retrieved documents - Checking if a summary is faithful to the source text - Auditing whether context was ignored in a customer support bot

ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.1/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description goes beyond annotations by disclosing a critical behavioral trait: the tool measures provenance and can pass answers that borrow vocabulary but change facts. It advises surfacing the 'handoff' field and escalating fact checks, adding valuable context beyond the readOnlyHint, idempotentHint, and destructiveHint annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear purpose statement upfront, followed by explanation of SGI, usage importance, and examples. It is slightly verbose (e.g., the ratio formula could be concise), but overall efficient and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (3 inputs, clear output schema present), the description fully covers its purpose, usage, return value (JSON with CHECK, score, distances), and example use cases. No gaps are evident.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides detailed descriptions for all three parameters (question, context, response). The description repeats this info with minimal added value ('Args: params (SGIInput): ...'), so it does not significantly enhance parameter understanding beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool checks whether an LLM response engaged a source document, with emphasis on provenance. However, it does not explicitly distinguish from sibling tools (groundlens_check, groundlens_dgi), though it implies a unique use case for RAG pipeline verification.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear guidance on when to use this tool ('for RAG pipeline verification') and hints at when not to (escalate fact-level verification elsewhere). However, it does not explicitly name alternative tools, missing an opportunity to differentiate from siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.5/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: groundlens_check is the main entry point that automatically selects the appropriate method, while groundlens_dgi and groundlens_sgi are the specific implementations for no-context and with-context scenarios, respectively. There is no overlap or ambiguity.

Naming Consistency5/5

All tools follow a consistent 'groundlens_' prefix pattern with specific suffixes (check, dgi, sgi) that clearly indicate their function. The naming convention is uniform and predictable.

Tool Count5/5

Three tools is an appropriate number for this narrow domain: a main dispatcher and two specialized methods. The count is well-scoped and each tool serves a distinct, justified purpose.

Completeness4/5

The tool set covers the core use cases (groundedness check with and without context) and includes an automatic selector. While there is no batch processing or detailed explanation tool, the surface is largely complete for the stated purpose.

Maintenance

ActivityActive
ResponsivenessSyncing

Resources

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/groundlens-dev/groundlens-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server