zeroH MCP (zeroh-mcp)

zeroH MCP is the official Model Context Protocol (MCP) server and Python SDK for the zeroH Deterministic AI Hallucination Guardrail & Step-by-Step Proof Ledger.

It enables AI coding assistants, autonomous agents, and IDE environments (Claude Desktop, Antigravity IDE, Cursor, Windsurf, and custom MCP hosts) to intercept arithmetic/algebraic hallucinations, seal multi-step reasoning chains with SHA-256 Merkle commitments, and bridge seamlessly to the zeroH Sovereign Enclave—while keeping all proprietary Sovereign Invariant Formulas, baselines, and canonical ledger tensors 100% vaulted and non-exposed.

Architectural Highlights & IP Boundary

zeroH-MCP operates across a strict Dual-Tier Split-Enclave Architecture:

1. Tier 1 — Public Open-Boundary AST Verifier (Zero-Config Local Mode):

   • Works out-of-the-box with zero external dependencies.

   • Exact Rational Arithmetic (compute, validate_claim): Evaluates numerical expressions via Python ast and fractions.Fraction to eliminate floating-point drift and catch calculation hallucinations (12 * 12 = 145 $\rightarrow$ REJECTED_HALLUCINATION).

   • Algebraic Substitution Verification (solve_equation, verify_step): Solves equations and verifies every candidate root by exact substitution.

   • Tamper-Evident SHA-256 Step Ledger (verify_step, session_report): Tracks step-by-step reasoning chains and issues a FULLY_PROVEN cryptographic seal only when every active step in the chain is verified.

   • Byzantine Fault Tolerant (BFT) Epistemic Consensus (epistemic_consensus): Classifies multi-agent proposals across the 4-tier epistemic lattice (QATI, ZANNI_GHALIB, SHAKK, WAHM) with automatic hallucination veto.

2. Tier 2 — Remote Sovereign Enclave Bridge (ZEROH_API_URL + ZEROH_API_KEY):

   • When configured with a zeroH Enterprise Enclave key, zeroh-mcp routes deep verification and canonical token interception (intercept_token, validate_claim, zk_verify_receipt) to the air-gapped Sovereign Enclave over HTTPS.

   • All proprietary invariant constants, closed-form equations, and canonical ledger tensors remain strictly inside the remote enclave; only normalized Coherence Index ($0.0 - 1.0$), Confidence Score ($0% - 100%$), Deterministic Status, and Cryptographic Receipts are returned.

Related MCP server: Mcp-Omega-Brain

Quick Start

1. Installation

git clone https://github.com/khurramcr7/zeroH-MCP.git
cd zeroH-MCP
pip install -e .

(Optional) Install sympy for extended symbolic algebra support:

pip install -e ".[symbolic]"

2. Configure in Claude Desktop / Cursor / Antigravity IDE

Add the following to your MCP configuration file (claude_desktop_config.json, .cursor/mcp.json, or Antigravity MCP settings):

{
  "mcpServers": {
    "zeroh-mcp": {
      "command": "python",
      "args": ["-m", "zeroh_mcp.server"],
      "env": {
        "ZEROH_API_URL": "",
        "ZEROH_API_KEY": ""
      }
    }
  }
}

Exposed MCP Tools (9 Deterministic Tools)

Python SDK & CLI Usage

CLI (zeroh-cli)

# Validate a claim from the terminal
python -m zeroh_mcp.cli "In exact arithmetic, 144 / 12 = 12"

# Output raw JSON receipt
python -m zeroh_mcp.cli --json "12 * 12 = 145"

# Check Sovereign Enclave & IP protection status
python -m zeroh_mcp.cli --status

Python SDK (ZeroHClient)

from zeroh_mcp import ZeroHClient

client = ZeroHClient()

# 1. Intercept calculation hallucinations
receipt = client.validate("The square of 15 is 15 * 15 = 225.")
print(receipt["deterministic_status"], receipt["confidence_score"])
# -> VERIFIED_COMPUTED_PASS 100.0%

# 2. Step-by-step cryptographic proof ledger
client.verify_step("session_1", {"kind": "compute", "expr": "3 * 19", "value": "57"})
client.verify_step("session_1", {"kind": "solve", "equation": "x**2 - 9 = 0", "claimed": {"x": 3}})
seal = client.session_report("session_1")
print(seal["seal"], seal["merkle_head_hash"])
# -> FULLY_PROVEN <64-char sha256>

Security & Zero-Leakage Audit

Run the automated IP & Formula Non-Exposure Audit and test suite at any time:

python scripts/security_audit_no_leaks.py
pytest -v

See SECURITY_AND_IP_BOUNDARY.md for full details on how proprietary formulas remain 100% isolated inside the Sovereign Enclave.