hallucc-mcp

HallucC MCP Server is an MCP server for AI hallucination detection and agent security, containing five tools, and can be used with Claude Code / Cursor / Claude Desktop.

1. Main capabilities

2. Claim-by-claim hallucination detection: provides a verdict, confidence, and sources for each claim (real verification report examples can be viewed on the official website).

3. Agent trajectory evaluation.

4. L0-L3 risk grading gating for Computer-Use Agent (CUA) actions.

5. Static audit of agent source code.

6. Prompt injection / jailbreak protection for 40+ features.

7. Tightening mechanism for CUA action gating

• Actions that leave task_scope are raised by one level (L0→L1, L1→L2, L2 remains L2 with an added "outside task scope" reason, L3 unchanged). This mechanism only tightens, never relaxes; omitting task_scope has no effect.
• Credential fields and payment/login domains trigger a takeover verdict (pause and wait for the user to enter it themselves — the agent never enters passwords).
• Multi-agent scenarios (Claude Code Task subagents, Codex agents, Kimi, etc.): the parent agent reads a credential file (its own L0) → the subagent sends it out (its own L2); a single hop is harmless, but as chained behavior it is dangerous. After attaching a delegation chain field to each action, the backend appends chain_trace: when cross-agent propagation exists, the chain aggregate level is raised to L3 and risk_diluted is set (a laundering signal). When the chain field is left empty, behavior is unchanged bit for bit, and existing callers need no changes.
• The ruleset_version in the response can be used to check whether online detection and the local Gate are running the same ruleset version.

1. Usage A. Hosted endpoint (recommended, no local setup required)

• The MCP server is hosted at https://aihcc.cloud/mcp（远程，streamable-http）。
• Cursor / Claude Desktop usage is the same: the URL is https://aihcc.cloud/mcp，请求头 Authorization: Bearer <key>.
• At https://aihcc.cloud create an API key (register → /keys), including a free daily quota.

B. Run via npx (stdio, no cloning required)

• The same five tools, via stdio transport; the key comes from an environment variable, and requests point to the hosted backend by default https://aihcc.cloud/api。
• The base URL must retain the /api prefix: nginx only proxies /api/ to the backend. Bare https://aihcc.cloud will reach the frontend — the request returns 200 with an HTML body, silently failing (audit and fallback files are both empty), and audit replay remains empty.

C. Run locally from source

• The server listens on http://127.0.0.1:8787/mcp；健康检查 GET /health.

Claude Code (CLI) configuration: Settings → MCP → Add MCP server:

• URL: http://127.0.0.1:8787/mcp
• Headers: {"Authorization": "Bearer <your HallucC API key>"}

The Claude Desktop configuration file is located at ~/Library/Application Support/Claude/claude_desktop_config.json.

MCP Inspector can be used for debugging—the tool list and authentication work without consuming quota.

IV. Authentication Model

• Each client sends Authorization: Bearer <your HallucC API key> → the server forwards it as-is to the backend → the backend validates it and deducts from the same account quota as the Web app. The key is transmitted only in the HTTP header—it never appears in tool parameters, nor in model records.
• Authentication at the MCP layer has two levels. tools/call (and any non-discovery method) requires a key with a valid format (hc_ + 48 hexadecimal digits); otherwise it returns a 401 JSON-RPC and does not contact the backend. The format check is a local regex with no backend round trip.
• Discovery methods (initialize, tools/list, ping, notifications/initialized) remain open and require no authentication, so that registries and directory sites can index the server: they do not make backend calls and do not expose user data. Setting MCP_ALLOW_ANON_DISCOVERY=0 restricts these methods as well.
• The actual validity of the key (existence, revocation, expiration) is always determined by the backend verify_api_key; the MCP-layer check only rejects tokens that cannot possibly be real keys.
• Key valid but quota exhausted → backend 429, mapped to "free quota exhausted, resets tomorrow or upgrade".
• Every tool response includes a quota object (backend quota_status), from the same source as the Web dashboard, decremented per call.
• Both check_cua_actions and check_cua_code_audit are pure rules—no LLM, no quota cost, safe for high-frequency use.

V. Transport and Registration

• Streamable HTTP (the remote transport currently recommended by the MCP specification, formerly known as HTTP+SSE), stateless mode: each POST startsa new transport + McpServer, then closes when done. Native support for Claude Code / Cursor / Claude Desktop. To support legacy SSE-only clients, SSEServerTransport can be added (dual endpoints /sse + /messages).
• Already listed in: the official MCP Registry (io.github.fredyee/hallucc v0.1.9, active), ModelScope MCP Square (@hallucC/hallucc), and the Coze Store (HallucC Fact-Check Assistant).

VI. Use Cases

• Scenarios that require item-by-item fact-checking and source tracing of claims in AI output.
• Scenarios that require evaluating agent execution traces.
• Scenarios that require risk-graded gating of computer-use agent actions.
• Scenarios that require static auditing of agent source code.
• Scenarios that require defense against prompt injection / jailbreaks.
• Cross-agent risk propagation detection in multi-agent delegation chains.

VII. Limitations

• The Web app provides 3 free checks per day; the free daily quota is limited, and once used up the backend returns 429 (the materials state that it resets tomorrow or you can upgrade).
• CUA action gating and code auditing are pure rule-based implementations and do not consume quota; other tool calls deduct quota.
• The materials do not provide specific pricing, information beyond the scope of platform support, effectiveness metrics, or complete usage steps, so these are not provided here.