ZPL Engine MCP Server

Model Context Protocol (MCP) server for the Zero Point Logic Engine — a post-binary stability and neutrality analysis system.

Connects any MCP-compatible AI client (Claude Desktop, Claude Code, Cursor, Windsurf, etc.) to the ZPL Engine API for real-time bias detection, stability scoring, and neutrality analysis across multiple domains.

69 tools (65 unique + 4 backwards-compat aliases) across 11 categories: Core, Finance, Gaming, AI/ML, Security, Crypto, Certification, Advanced, Universal, Meta, and AI Eval.

Highlights of the 4.x line

For what changed in the release you are installing, see CHANGELOG.md.

Two months of incremental work consolidated. 21 bugs fixed, 308 tests (259 unit + 49 live MCP integration), Windows + Linux verified. Backwards compatible — legacy zpl_u_<48hex> keys still work, all 69 tools keep the same input shape.

New commands

• npx zpl-engine-mcp setup — now memory-aware. Detects existing config and offers keep / re-setup / patch-only instead of forcing a fresh login. --force bypasses.
• npx zpl-engine-mcp whoami — shows which account this install is logged into.
• npx zpl-engine-mcp repair — wipes local config + removes the entry from each MCP client config (Claude Desktop, Cursor, Windsurf). Preserves unrelated entries. --yes skips confirmation.
• npx zpl-engine-mcp --help / --version — POSIX-standard usage and version flags.
• zpl_diagnose MCP tool — full health report (config + key + engine + auth) for issue reports.

Critical fixes

• API key regex now accepts wizard-issued keys with type prefixes (zpl_u_mcp_, zpl_u_cli_, zpl_u_default_). Pre-4.0 the wizard install always failed silently.
• Cloudflare HTML responses explained — actionable error messages with cf-ray ID instead of generic 403.
• Smoke test at end of setup — catches replication lag between wizard approval and engine acceptance.
• Secret sanitizer in history — no longer leaks wizard-prefixed ZPL keys or full Anthropic sk-ant-* tokens (regex was truncating at first hyphen).
• Safety bounds on numeric env vars — ZPL_RATE_LIMIT clamped to [1, 600], ZPL_MAX_RETRIES to [0, 5].

Tool fixes

• zpl_simulate 0/0 result on positive inputs (switched to distributionBias + identical-input short-circuit).
• zpl_liquidity table/verdict misalignment (verdict now cites per-pool counts).
• zpl_quota plan auto-detection from config.toml (env > config > "free").
• zpl_quota + zpl_alert token estimate accuracy — 22 tools now persist real tokens_used instead of hardcoded heuristic.
• zpl_teach snippet referenced never-published @zeropointlogic/engine-mcp package name.
• Duplicate Claude Desktop entries auto-deduplicated on setup.
• LANGUAGE dead-code env var removed.

See CHANGELOG for the complete list with rationales.

What's new in v3.7.0

• Setup wizard auto-configures Cursor and Windsurf, not just Claude Desktop. Each run patches claude_desktop_config.json, ~/.cursor/mcp.json, and ~/.codeium/windsurf/mcp_config.json in a single pass. Clients that aren't installed are skipped silently; each patch is isolated so one missing client never blocks the others. Empty pre-existing config files (common for Cursor's stub {"mcpServers":{}}) are now handled correctly.

What's new in v3.6.1

• Free plan quota corrected — all docs/copy now show 5,000 tokens/month (was erroneously "500 tokens / ~14 days" in early migration draft). Engine-side was already 5,000; this release just syncs the MCP. See CHANGELOG.

What's new in v3.6.0

• npx zpl-engine-mcp setup — one-command device-flow wizard: opens browser, authenticates with your ZPL account, creates a per-machine API key, and auto-patches claude_desktop_config.json. No more copy-paste.
• User-key only — ZPL_SERVICE_KEY fallback removed. MCP requires a zpl_u_... user key so plan limits apply per account.

What's new in v3.4.3

• Local dev fix — with ZPL_ENGINE_ALLOW_INSECURE_LOCAL=1, localhost / 127.0.0.1 / ::1 are accepted as engine hostnames (not only production). Use with http://127.0.0.1:PORT for a local engine.
• Version from package.json — MCP version field, update check, and report footers no longer hardcode semver strings.
• npm test — regression tests for engine URL validation (npm run build && node --test test/engine-url.test.mjs).

What's new in v3.4.2

• Engine URL hardening — default allowlist is engine.zeropointlogic.io only. Self-hosted engines: set ZPL_ENGINE_HOST_ALLOWLIST=your.hostname. Local HTTP: ZPL_ENGINE_ALLOW_INSECURE_LOCAL=1 with http://127.0.0.1 only. Optional ZPL_ENGINE_DISABLE_URL_GUARD=1 disables hostname checks (not recommended). All engine fetch calls use redirect: "error" so redirects cannot carry your Bearer token to a new origin.

What's new in v3.4.1

• v3.4.1 — Bug fixes: fixed zpl_consistency_test bias inversion (inconsistent responses now correctly lower AIN), session-budget double-counting on Claude eval tools (upfront reservation instead of post-increment), zpl_alert budget calc that silently always said "OK" (now uses the same estimate as zpl_quota), zpl_validate_input stack overflow on very large arrays (reduce loop instead of Math.min(...values)), version-check cache ignoring its own 24h window (fixed filename instead of PID-suffixed), stale version strings in zpl_account/zpl_report output. Store now honours ZPL_STORE_PATH (documented) in addition to legacy ZPL_STORE_DIR. CSV export now escapes embedded commas/quotes. API key format is validated client-side (fail-fast on obvious mis-paste, prevents accidentally leaking unrelated secrets in the Authorization header). Removed an internal engine-method reference from zpl_check_response output. Core zpl_sweep and zpl_analyze now honour the per-minute rate limiter.
• v3.4.0 — 8 new AI Eval tools (zpl_consistency_test, zpl_sycophancy_score, zpl_refusal_balance, zpl_language_equity, zpl_persona_drift, zpl_safety_boundary, zpl_hallucination_consistency, zpl_emotional_stability) that run prompts through Claude and score response distributions with the ZPL engine. Requires a separate ANTHROPIC_API_KEY env var. Session budget cap of 100 Claude calls per process to prevent accidental spend. Multilingual propaganda-detection update for zpl_news_bias / zpl_review_bias: EN + RO + FR + DE + ES + IT keyword lists with a symmetric uniformity penalty (100% positive-only OR 100% negative-only texts trigger the same bonus).
• v3.3.0 — Added 4 clearer "balance"-prefixed aliases: zpl_balance_check (= zpl_decide), zpl_balance_compare (= zpl_versus), zpl_balance_pair (= zpl_compare), zpl_balance_rank (= zpl_rank). Both old and new names work; old names get a DEPRECATED note in their description. Existing users keep working without changes.
• v3.2.0 — 4 new tools: zpl_about (project info, no auth), zpl_quota (remaining tokens), zpl_score_only (minimal JSON for CI/CD), zpl_validate_input (free validation). Auto-update check, friendlier signup message, hard disclaimers on hypothetical/bias tools, RNG sample-size warnings, and bias tools re-framed as "language balance" instead of "fake/biased".
• v3.1.0 — Added ZPL_MODE env var (pure | coach). Pure mode hides AIN scores from the AI on text-evaluation tools (zpl_check_response, zpl_news_bias, zpl_review_bias) to prevent reactivity bias / observer effect.
• v3.0.0 (BREAKING) — Removed 5 tools that created false-authority risk: zpl_ask, zpl_certify, zpl_certificate, zpl_predict, zpl_auto_certify. AIN is a STABILITY measurement only — never a prediction or recommendation.

Setup (free, 15 seconds)

Run this in your terminal — it authenticates you, creates an API key, and writes your Claude Desktop config for you:

npx zpl-engine-mcp@latest setup

The wizard will:

1. Open your browser to approve the CLI (sign up if you don't have an account — free, 5,000 tokens/month, no credit card)
2. Save the key to ~/.zpl/config.toml (chmod 600)
3. Patch the MCP config of every supported client that's installed:
   • Claude Desktop — claude_desktop_config.json
   • Cursor — ~/.cursor/mcp.json
   • Windsurf — ~/.codeium/windsurf/mcp_config.json
4. Print which clients were configured and which to restart.

That's it. Clients that aren't installed are skipped silently. If you're using a client we don't auto-detect (Claude Code, VS Code, Zed, ...), the wizard prints the exact JSON snippet to paste into that client's MCP config.

{
  "mcpServers": {
    "zpl-engine": {
      "command": "npx",
      "args": ["-y", "zpl-engine-mcp@latest"],
      "env": {
        "ZPL_API_KEY": "zpl_u_YOUR_KEY_HERE",
        "ZPL_MODE": "pure"
      }
    }
  }
}

What is ZPL Engine?

The ZPL Engine computes the AIN (AI Neutrality Index) — a mathematical measure of how stable or biased a system is. It works across: