haluguard-mcp

MCP server for haluguard — an opt-in fact-check + security scanner for LLM responses. Plugs into Claude Code, Cursor, ChatGPT Desktop, Continue, and any other MCP-compatible host.

This package is a thin HTTP wrapper (~700 LOC, single file, no dependencies beyond the official MCP SDK). All detection logic lives in the hosted API at api.haluguard.com. The source is open at github.com/haluguard/haluguard-mcp — audit it yourself before installing.

What this does (and doesn't)

Does:

• Exposes 5 tools to your MCP host (haluguard_check, haluguard_verify_and_correct, haluguard_verdict, haluguard_my_stats, haluguard_diagnose).
• When the assistant calls one of those tools, this server forwards the request body — the response text + (optionally) the user's prompt — to api.haluguard.com/v1/check with your bearer token.
• Returns the verification result (findings + sources) back to the assistant.

Doesn't:

• Run any heuristic locally. The 46 verifiers (Wikidata lookups, OSV CVE checks, Bandit/Semgrep SAST, etc.) all run server-side.
• Modify your CLAUDE.md automatically — the setup subcommand does that but only when you explicitly invoke it from your terminal, and only the block between <!-- haluguard-start --> and <!-- haluguard-end -->.
• Phone home with telemetry that isn't tied to a request you made.
• Store, log, or train on the text the assistant sends through it (privacy policy: haluguard.com/privacy).
• Instruct the assistant to hide its presence from you. The MCP tool descriptions and the CLAUDE.md template explicitly tell the assistant it's free to mention to you that haluguard was consulted.

Install (1 command, terminal)

The recommended install is one terminal command:

HALUGUARD_TOKEN=hg_live_xxxx npx -y haluguard-mcp@latest setup

This:

1. Registers haluguard as an MCP server in your Claude Code config.
2. Adds a transparent helper block to ~/.claude/CLAUDE.md (you can open the file afterwards and review or remove it).
3. Smoke-tests the connection.

Get your HALUGUARD_TOKEN after subscribing at haluguard.com.

Manual install (Cursor / Continue / generic MCP host)

Add to your mcp.json:

{
  "mcpServers": {
    "haluguard": {
      "command": "npx",
      "args": ["-y", "haluguard-mcp"],
      "env": { "HALUGUARD_TOKEN": "hg_live_xxxx" }
    }
  }
}

Uninstall (1 command + 1 follow-up)

# Step 1 — clean up the CLAUDE.md block + auto-setup marker:
npx -y haluguard-mcp@latest uninstall

# Step 2 — Claude Code's own config (we don't touch it from this process):
claude mcp remove haluguard

The uninstall subcommand:

• Removes only the block between <!-- haluguard-start --> and <!-- haluguard-end --> markers in ~/.claude/CLAUDE.md — leaves the rest of your CLAUDE.md untouched.
• Creates a backup at ~/.claude/CLAUDE.md.haluguard-uninstall-backup before any write — so you can recover if you change your mind.
• Use --dry-run to preview without writing anything.
• Use --project to act on the project-local ./CLAUDE.md instead.

Optional final step: revoke your token at https://app.haluguard.com/dashboard.

Tools

| Tool | What it does | |---|---| | haluguard_check | Full check on a response. Returns findings + sources. | | haluguard_verify_and_correct | Same check + a pre-built corrected version when findings exist. | | haluguard_verdict | Lightweight verdict + score (no per-finding evidence). | | haluguard_my_stats | Your own usage stats — requests / hallucination rate / cost. | | haluguard_diagnose | Health check (API reachable, token valid, smoke test). |

What gets verified

46 verifiers across three pillars (the assistant's response text is sent to the API — the API runs the verifiers — results come back):

Factual (34): Wikidata, Wikipedia, Crossref, arXiv, Semantic Scholar, OpenAlex, SEC EDGAR, World Bank, GitHub, PyPI/npm/Cargo/RubyGems, OSV CVE database, OpenLibrary, MusicBrainz, ConceptNet (common-sense KB, with local snapshot), PubChem, OpenStreetMap/Nominatim, Python AST, package introspection DB, etc.

Security (7): Bandit (Python SAST), Semgrep (multi-lang SAST), gitleaks (secrets DB, ~195 patterns), Microsoft Presidio (PII), Detoxify (open-weights toxicity model), prompt-injection regex + semantic corpus of 703 known attacks.

Quality (5): Refusal detection, gibberish detection, language mismatch, citation density (weasel phrases without sources), overclaim density (absolute words like "always" / "never" / "100%").

Each finding includes standard_refs mapping to CWE / OWASP LLM Top 10 / GDPR articles / NIST AI RMF functions / SPDX license IDs when applicable.

Transparency & data handling

• What's sent: the response text the assistant is about to send, and optionally the user prompt. Nothing else.
• What's stored: per-request audit log entries (verdict + finding count + timestamp + token hash). Full request text is NOT stored — see the privacy policy.
• Where stored: PostgreSQL on Railway (US-East). Enterprise tier offers EU-region storage + customer-region self-hosting.
• Retention: 30 days for individual tier, configurable for enterprise.
• Encryption: TLS in transit, AES-256 at rest.
• GDPR: Right-to-deletion API available (DELETE /v1/user-data).

Full security disclosure: SECURITY.md.

Cost

• Free tier: 1,000 verification requests / month
• Individual: $5/month — unlimited
• Team: $499/month
• Enterprise: contact

No per-verifier markup — every plan gets all 46 verifiers.

License

MIT. See LICENSE.