HallucC — Hallucination & Safety Guardian

HallucC MCP Server

[中文文档](./README_zh.md) ｜ Live Demo ｜ Official MCP Registry

Give your AI a fact-checker and a safety gateway: claim-by-claim hallucination detection, agent trajectory evaluation, L0-L3 risk gating for Computer-Use Agent (CUA) actions, Agent source code static audit, and a 40+ feature prompt-injection / jailbreak guard — one MCP server, five tools, works with Claude Code / Cursor / Claude Desktop.

See it first — no sign-up required

• 🔍 A real verification report (per-claim verdicts + confidence + sources): https://aihcc.cloud/r/GttouoJfMpkC
• 🛡️ Try CUA action gating online (rule-based, free, no quota cost): https://aihcc.cloud/cua
• 📝 Web app (3 free checks per day): https://aihcc.cloud

Tools (5)

Auth model: each client sends Authorization: Bearer → the server forwards it as-is to the backend → the backend validates and deducts from the same account quota as the web app. Keys travel only in HTTP headers — never in tool arguments, never in model transcripts.

The tightening capabilities of check_cua_actions

An action that leaves task_scope is escalated one level (L0→L1, L1→L2, L2 stays L2 with an "outside task scope" reason appended, L3 unchanged). This mechanism only tightens and never loosens; omitting task_scope has no effect. Credential fields and payment/login domains yield a takeover verdict (suspend and wait for the user to type it themselves — the agent never types your password).

Multi-agent setups (Claude Code Task subagents, Codex agents, Kimi, …): a parent agent reading a credential file (L0 on its own) → a subagent posting it out (L2 on its own) is harmless per hop and dangerous as a chain. Attach the delegation-chain fields to each action and the backend appends a chain_trace: when cross-agent propagation exists the chain aggregate level is raised to L3 and risk_diluted is set (the laundering signal). Leave the chain fields empty and behaviour is bit-for-bit unchanged — existing callers need no change.

The response's ruleset_version lets you verify that online detection and the local Gate run the same rule version.

Hosted endpoint (recommended, zero local setup)

The MCP server is hosted at https://aihcc.cloud/mcp (remote, streamable-http). Point your client at it with your API key:

# Claude Code

claude mcp add --transport http hallucc https://aihcc.cloud/mcp \ --header "Authorization: Bearer "

Cursor / Claude Desktop work the same way: URL https://aihcc.cloud/mcp, header Authorization: Bearer . Create your API key at https://aihcc.cloud (register → /keys). Free daily quota included.

Or: run via npx (stdio, no clone needed)

{

"mcpServers": { "hallucc": { "command": "npx", "args": ["-y", "hallucc-mcp"], "env": { "HALLUCC_API_KEY": " " } } } }

Same five tools over stdio transport; the key comes from the environment and requests default to the hosted backend https://aihcc.cloud/api.

The base URL must keep the `/api` prefix: nginx only proxies /api/ to the backend. A bare

https://aihcc.cloud reaches the frontend instead — the request returns 200 with an HTML body,

fails silently (nothing lands in audit or in a fallback file), and the audit replay stays empty.

Run locally (from source)

# 1. Install dependencies

npm install

2. (Optional) configure backend address & port; defaults to local :8001

cp .env.example .env

HALLUCC_BASE_URL=http://127.0.0.1:8001

PORT=8787

3. Make sure the backend is up: curl http://127.0.0.1:8001/health

4. Start the MCP server (dev with hot reload)

npm run dev

or production: npm start

The server listens on http://127.0.0.1:8787/mcp; health check GET /health.

Client setup

Claude Code (CLI)

claude mcp add --transport http hallucc http://127.0.0.1:8787/mcp \

--header "Authorization: Bearer "

claude mcp list

then in conversation: ask Claude to fact-check a passage or scan a prompt for injection

Cursor

Settings → MCP → Add MCP server:

• Type: http
• URL: http://127.0.0.1:8787/mcp
• Headers: {"Authorization": "Bearer "}

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json:

{

"mcpServers": { "hallucc": { "type": "http", "url": "http://127.0.0.1:8787/mcp", "headers": { "Authorization": "Bearer " } } } }

MCP Inspector (debug — tool list & auth work without spending quota)

npx @modelcontextprotocol/inspector

choose Streamable HTTP, URL http://localhost:8787/mcp

add Custom Header: Authorization: Bearer

Auth & quota

• Auth is two-tier at the MCP layer. tools/call (and any non-discovery method) requires a format-valid key — hc_ + 48 hex — else 401 JSON-RPC, before the backend is contacted. The format check is a local regex, no backend round-trip.
• Discovery methods (initialize, tools/list, ping, notifications/initialized) stay open unauthenticated so registries and directory sites can index the server: they make no backend call and expose no user data. Set MCP_ALLOW_ANON_DISCOVERY=0 to gate those too.
• Actual key validity (existence, revocation, expiry) is always decided by the backend's verify_api_key; the MCP-layer check only rejects tokens that can't possibly be real keys.
• Valid key but quota exhausted → backend 429, mapped to "free quota exhausted, resets tomorrow or upgrade".
• Every tool response includes a quota object (backend quota_status), same source as the web dashboard, decremented per call.
• check_cua_actions and check_cua_code_audit are both pure rules — no LLM, no quota cost, safe for high-frequency use.

Project layout

src/

server.ts Express + StreamableHTTP transport (stateless) + auth middleware + tool registration context.ts config loading + API key extraction backend.ts BackendClient (key pass-through, unified 401/429/5xx mapping) + toMcpResult schemas.ts zod input schemas for the 5 tools (aligned with backend Pydantic Fields) tools/ verifyText.ts → /detect verifyAgent.ts → /detect-agent checkCuaActions.ts → /cua/classify checkCuaCodeAudit.ts → /cua/audit-code checkSafety.ts → /guard/check (fast → /guard/check-fast) index.ts registerAllTools

Transport

Streamable HTTP (the remote transport recommended by the current MCP spec, formerly "HTTP+SSE"), stateless mode: each POST spins up a fresh transport + McpServer and closes when done. Natively supported by Claude Code / Cursor / Claude Desktop. To support legacy SSE-only clients, add SSEServerTransport (dual endpoints /sse + /messages).

Listed on

• ✅ Official MCP Registry: io.github.fredyee/hallucc v0.1.11 (active)
• ✅ ModelScope MCP Square: @hallucC/hallucc
• ✅ Coze Store: HallucC Fact-Check Assistant

License

MIT