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.

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

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 your claude_desktop_config.json to add zpl-engine-mcp under mcpServers
4. Print "Restart Claude Desktop to activate."

That's it. Claude Desktop detected? Wizard adds the entry automatically. Using Claude Code / Cursor / Windsurf? The wizard prints the exact JSON snippet to paste into your 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:

• Finance — market stability, portfolio bias, risk concentration, forex pairs, fear & greed
• Gaming — economy balance, loot fairness, matchmaking, gacha audit, PvP balance
• AI/ML — model fairness, prediction bias, dataset balance, prompt testing, benchmarks
• Security — vulnerability distribution, risk matrix, compliance scoring
• Crypto — whale concentration, DeFi risk, liquidity analysis, tokenomics
• Certification — language-balance check on text, debate balance, news balance, review authenticity
• Universal — quick decisions, structured comparison, AIN ranking, response balance check

One engine, multiple domains. The engine doesn't know what your data represents — domain "lenses" translate your specific data into the universal mathematical framework.

Modes (ZPL_MODE)

ZPL Engine MCP supports two modes for how text-evaluation results are returned:

Why this matters: stability scoring only works if the measurement doesn't change the thing it measures. If an AI sees "AIN = 42" and then writes the next paragraph, its language naturally drifts to justify the score. Pure mode breaks that feedback loop.

Set via env: "ZPL_MODE": "pure" or "ZPL_MODE": "coach".

Installation

Via npm (recommended):

npm install zpl-engine-mcp

Or clone and build:

git clone https://github.com/cicicalex/zpl-engine-mcp.git
cd zpl-engine-mcp
npm install
npm run build

Alternative client configs

Claude Code CLI (.claude/settings.json)

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

Local build

{
  "mcpServers": {
    "zpl-engine": {
      "command": "node",
      "args": ["/path/to/engine-mcp/dist/index.js"],
      "env": {
        "ZPL_API_KEY": "zpl_u_YOUR_KEY_HERE"
      }
    }
  }
}

Cursor / Windsurf

Add to your MCP configuration following the respective IDE's documentation, with the same command/args/env structure.

Tool Categories (67 tools)

Unique tool names: 63. With 4 backwards-compat aliases (zpl_balance_* pairs) the registered total is 67.

New in v3.2: Meta tools

v3.0.0 Removed Tools (and why)

Quick Examples

> Analyze my crypto portfolio for balance: BTC 40%, ETH 25%, SOL 15%, AVAX 10%, DOT 10%

> Check if this loot table is fair: Common 60%, Uncommon 25%, Rare 10%, Legendary 5%

> Is my ML model output balanced? Class A: 1200 predictions, Class B: 300 predictions

> Check this AI response for language balance

> Compare React vs Vue across 5 criteria

Pricing Plans

All paid plans offer 20% discount with annual billing.

Token Cost

Token cost depends on the dimension tier:

API Key Management

• Keys are generated at zeropointlogic.io/dashboard/api-keys
• Format: zpl_u_ + 48 hex characters (user keys). v3.5.0+: the MCP only accepts user keys. Service keys (zpl_s_...) are engine-to-engine only — server-side, IP-restricted, not MCP-usable.
• Keys are SHA-256 hashed server-side — the plaintext is shown once at creation
• To rotate a key: create a new key, update your MCP config, restart Claude, then delete the old key
• If a key is compromised, delete it immediately from the dashboard — it's invalidated instantly

Environment Variables

Architecture

Your AI Client (Claude, Cursor, etc.)
    |
    v (MCP Protocol — stdio)
ZPL Engine MCP Server (this package)
    |
    +-- Tool modules (data -> engine params)
    |   +-- finance, gaming, ai-ml, security, crypto
    |   +-- certification, advanced, universal, meta
    |
    v (HTTPS — Bearer auth)
ZPL Engine API (engine.zeropointlogic.io)
    |
    v (Post-binary computation)
    AIN Result (0.1-99.9)

The MCP server never sees or contains the engine formula. It sends (d, bias, samples) and receives (ain, deviation, status). All computation happens server-side.

Security

• All inputs validated via Zod schemas with strict maxLength limits
• API keys never logged or stored in plaintext locally
• Engine URL allowlist — requests only go to engine.zeropointlogic.io unless you add hosts with ZPL_ENGINE_HOST_ALLOWLIST. Rejects userinfo embedded in ZPL_ENGINE_URL (use env vars for keys). fetch(..., { redirect: "error" }) prevents following HTTP redirects that could send your Bearer token elsewhere.
• In-memory rate limiting (configurable)
• Exponential backoff retry for transient engine failures (5xx only, not 4xx)
• Fail-fast startup if ZPL_API_KEY is not set (except for no-auth tools)
• Local history sanitizes API key prefixes before writing

IP Protection (v3.0.0+)

The ZPL Engine computation method is a trade secret of Zero Point Logic. This MCP has been hardened to never expose it:

• Tool outputs return AIN score + status + tokens used only. No bias, deviation, p-output, dimension, or timing values are exposed.
• The MCP never receives or processes the engine formula — it sends (d, bias, samples) to the server and receives (ain, status) back.
• All computation happens server-side on the proprietary engine. The client-side code contains no algorithmic secrets.
• v3.0 removed tools that allowed user-provided scores to be presented as official AIN measurements (false authority risk).

License

MIT (covers the MCP client code only). The ZPL Engine computation algorithm, AIN formula, and server-side processing are proprietary trade secrets of Zero Point Logic and are NOT covered by this license.

Author

Ciciu Alexandru-Costinel — Zero Point Logic

Links

• ZPL Engine — Main site
• Finance Monitor — Live financial analysis
• API Documentation — Full API reference
• Pricing — Plans & API keys
• Smithery Registry — MCP discovery

See CHANGELOG.md for full version history.