zpl-engine-mcp
Advanced tools
MCP server for the ZPL stability engine — AIN bias detection & neutrality scoring for finance, gaming, AI/ML, security, crypto. 69 tools across 11 categories. Plug into Claude Desktop / Cursor / Windsurf in 10 seconds via `npx zpl-engine-mcp setup`. Free
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.
For what changed in the release you are installing, see CHANGELOG.md.
Two months of incremental work consolidated. 21 bugs fixed, 293 tests (244 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.
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.zpl_u_mcp_, zpl_u_cli_, zpl_u_default_). Pre-4.0 the wizard install always failed silently.sk-ant-* tokens (regex was truncating at first hyphen).ZPL_RATE_LIMIT clamped to [1, 600], ZPL_MAX_RETRIES to [0, 5].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.setup.LANGUAGE dead-code env var removed.See CHANGELOG for the complete list with rationales.
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.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.ZPL_SERVICE_KEY fallback removed. MCP requires a zpl_u_... user key so plan limits apply per account.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.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).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.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.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).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.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".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.zpl_ask, zpl_certify, zpl_certificate, zpl_predict, zpl_auto_certify. AIN is a STABILITY measurement only — never a prediction or recommendation.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:
~/.zpl/config.toml (chmod 600)claude_desktop_config.json~/.cursor/mcp.json~/.codeium/windsurf/mcp_config.jsonThat'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.
If you can't run the wizard (air-gapped install, policy restriction, etc.):
zpl_u_... key from /dashboard.{
"mcpServers": {
"zpl-engine": {
"command": "npx",
"args": ["-y", "zpl-engine-mcp@latest"],
"env": {
"ZPL_API_KEY": "zpl_u_YOUR_KEY_HERE",
"ZPL_MODE": "pure"
}
}
}
}
The ZPL Engine computes the AIN (AI Neutrality Index) — a mathematical measure of how stable or biased a system is. It works across:
One engine, multiple domains. The engine doesn't know what your data represents — domain "lenses" translate your specific data into the universal mathematical framework.
ain — returned by the engine on a 0.0 – 1.0 scale with 6 decimals. Human-readable tool output shows it on a 0 – 100 scale with its decimals kept (93.24/100), never rounded to a whole number. zpl_score_only returns the raw engine value untouched.ain_status — quality of the equilibrium: CERTIFIED_NEUTRAL, HIGHLY_NEUTRAL, NEUTRAL, MODERATE_BIAS, SIGNIFICANT_BIAS, HIGH_BIAS.status — a different field: the stability regime, STABLE, ACTIVE, INHIBITED_HIGH, INHIBITED_LOW. There is no plain INHIBITED value. Sweep steps carry status, not ain_status.ZPL Engine MCP supports two modes for how text-evaluation results are returned:
| Mode | Behavior | When to use |
|---|---|---|
pure (default) | AIN score is hidden from the AI on zpl_check_response, zpl_news_bias, zpl_review_bias. The AI gets a verdict category only; the user sees the numeric score separately. | Default for most users. Prevents the observer effect — once the AI knows the numeric score, its subsequent output can drift toward it, contaminating downstream analysis. |
coach | AIN score is exposed to the AI on all tools. | When you explicitly want the AI to reason about the score (e.g. teaching mode, debugging, writing articles about balance scores). |
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".
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
{
"mcpServers": {
"zpl-engine": {
"command": "npx",
"args": ["-y", "zpl-engine-mcp@latest"],
"env": {
"ZPL_API_KEY": "zpl_u_YOUR_KEY_HERE",
"ZPL_MODE": "pure"
}
}
}
}
{
"mcpServers": {
"zpl-engine": {
"command": "node",
"args": ["/path/to/engine-mcp/dist/index.js"],
"env": {
"ZPL_API_KEY": "zpl_u_YOUR_KEY_HERE"
}
}
}
}
Add to your MCP configuration following the respective IDE's documentation, with the same command/args/env structure.
69 tools across 11 categories: 65 unique names plus 4 backwards-compat aliases (the zpl_balance_* pairs, which reuse another tool's handler). Every row below is a live registration, so the table adds up to the same 69.
| Category | Tools | Examples |
|---|---|---|
| Core | 10 | zpl_compute, zpl_sweep, zpl_matrix, zpl_analyze, zpl_domains, zpl_health, zpl_plans, zpl_history, zpl_watchlist, zpl_report |
| Finance | 7 | zpl_market_scan, zpl_portfolio, zpl_fear_greed, zpl_forex_pair, zpl_sector_bias, zpl_macro, zpl_correlation |
| Gaming | 6 | zpl_loot_table, zpl_matchmaking, zpl_economy_check, zpl_pvp_balance, zpl_gacha_audit, zpl_rng_test |
| AI/ML | 4 | zpl_model_bias, zpl_dataset_audit, zpl_prompt_test, zpl_benchmark |
| Security | 3 | zpl_vuln_map, zpl_risk_score, zpl_compliance |
| Crypto | 4 | zpl_whale_check, zpl_defi_risk, zpl_liquidity, zpl_tokenomics |
| Certification | 3 | zpl_debate, zpl_news_bias, zpl_review_bias |
| Advanced | 7 | zpl_simulate, zpl_leaderboard, zpl_chart, zpl_teach, zpl_alert, zpl_versus (+ alias zpl_balance_compare) |
| Universal | 8 | zpl_check_response, zpl_explain, zpl_decide (+ alias zpl_balance_check), zpl_compare (+ alias zpl_balance_pair), zpl_rank (+ alias zpl_balance_rank) |
| Meta | 9 | zpl_about, zpl_quota, zpl_score_only, zpl_diagnose, zpl_validate_input, zpl_batch, zpl_export, zpl_usage, zpl_account |
| AI Eval | 8 | zpl_consistency_test, zpl_sycophancy_score, zpl_refusal_balance, zpl_language_equity, zpl_persona_drift, zpl_safety_boundary, zpl_hallucination_consistency, zpl_emotional_stability |
| Tool | Auth | Purpose |
|---|---|---|
zpl_about | No | Project info + doc links — works before signup |
zpl_quota | Yes | Remaining tokens this month, reset date |
zpl_score_only | Yes | Minimal JSON {ain, ain_status, status, tokens} for CI/CD pipelines — ain is the raw engine value (0.0-1.0), unrounded |
zpl_validate_input | No | Input validation with no token cost — sanity check before paying |
| Removed | Why | Replacement |
|---|---|---|
zpl_ask | Accepted user-provided scores → returned "official AIN" → false authority risk | zpl_decide, zpl_compare, zpl_rank |
zpl_certify | Generated "ZPL Certified" badge on arbitrary text → scam-tool risk | zpl_check_response (raw balance score, no certification claim) |
zpl_certificate | Generated "Certificate ID" + grades A+/F → enabled fake ZPL endorsements | None — manual review only |
zpl_predict | Name implies prediction; users misused for stock/lottery "predictions" | zpl_chart (historical visualization, no forecast) |
zpl_auto_certify | Forced AIN badge on every Claude response → spam + false authority at scale | None — explicit user requests only |
> 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
All paid plans offer 20% discount with annual billing.
| Plan | Monthly | Annual | Max D | Tokens/mo | Keys |
|---|---|---|---|---|---|
| Free | $0 | — | d=9 | 5,000 | 1 |
| Basic | $10/mo | $8/mo | d=16 | 10,000 | 1 |
| Pro | $29/mo | $23/mo | d=25 | 50,000 | 3 |
| GamePro | $69/mo | $55/mo | d=32 | 150,000 | 5 |
| Studio | $149/mo | $119/mo | d=48 | 500,000 | 10 |
| Agent | $199/mo | $159/mo | d=48 | 2,000,000 | 50 |
| Enterprise | $499/mo | $399/mo | d=64 | 10,000,000 | 25 |
| Enterprise XL | $999/mo | $799/mo | d=100 | 50,000,000 | 50 |
Token cost depends on the dimension tier:
| Dimension | Tokens/call | Sweep (19x) | Free plan (5,000, d<=9) |
|---|---|---|---|
| D3–D5 | 1 | 19 | 5,000 calls |
| D6–D9 | 2 | 38 | 2,500 calls |
| D10–D16 | 5 | 95 | — (needs Basic+) |
| D17–D25 | 15 | 285 | — (needs Pro+) |
| D26–D32 | 40 | 760 | — (needs GamePro+) |
| D33–D48 | 150 | 2,850 | — (needs Studio+) |
| D49–D64 | 500 | 9,500 | — (needs Enterprise) |
| D65+ | 2,000 | 38,000 | — (needs Enterprise XL) |
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.| Variable | Required | Default | Description |
|---|---|---|---|
ZPL_API_KEY | Yes* | — | Your user API key (zpl_u_... — 48 hex chars). *Optional for zpl_about and zpl_validate_input. Format is validated client-side. Service keys (zpl_s_...) are rejected from v3.5.0 — they're engine-to-engine only and use IP allowlisting instead of plan limits. |
ZPL_MODE | No | pure | pure hides AIN from AI on text-eval tools; coach exposes it. See Modes above. |
ZPL_ENGINE_URL | No | https://engine.zeropointlogic.io | Engine base URL (must match host allowlist; see Security) |
ZPL_ENGINE_HOST_ALLOWLIST | No | — | Extra allowed hostnames (comma-separated), e.g. staging.engine.example.com for self-hosted engines |
ZPL_ENGINE_ALLOW_INSECURE_LOCAL | No | unset | Set to 1 to allow http:// to localhost / 127.0.0.1 / ::1 and to treat those hostnames as allowed (no extra ZPL_ENGINE_HOST_ALLOWLIST needed for local dev) |
ZPL_ENGINE_DISABLE_URL_GUARD | No | unset | Set to 1 to skip hostname allowlist (dangerous; mistyped URLs could exfiltrate your API key) |
ZPL_RATE_LIMIT | No | 60 | Max requests per minute (applies to zpl_compute, zpl_sweep, zpl_analyze) |
ZPL_BUDGET_WARN | No | 500 | Token budget warning threshold |
ZPL_MAX_RETRIES | No | 2 | Retry count for transient engine failures (5xx only) |
ZPL_STORE_PATH | No | ~/.zpl-engine/ | Local history storage path (legacy alias: ZPL_STORE_DIR). Must resolve inside $HOME or the OS tmp dir; otherwise falls back to default. |
ANTHROPIC_API_KEY | Only for AI Eval tools | — | Required for the 8 AI Eval tools (zpl_consistency_test, etc.). Session capped at 100 Claude calls per process. |
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.0-1.0, 6 decimals)
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.
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.ZPL_API_KEY is not set (except for no-auth tools)The ZPL Engine computation method is a trade secret of Zero Point Logic. This MCP has been hardened to never expose it:
(d, bias, samples) to the server and receives (ain, status) back.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.
See CHANGELOG.md for full version history.
FAQs
MCP server for the ZPL stability engine — AIN bias detection & neutrality scoring for finance, gaming, AI/ML, security, crypto. 69 tools across 11 categories. Plug into Claude Desktop / Cursor / Windsurf in 10 seconds via `npx zpl-engine-mcp setup`. Free
We found that zpl-engine-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A misconfiguration gave three Anthropic models internet access, and one, believing it was in a simulation, shipped a credential-stealing package to PyPI.
Security News
/Company News
Socket has joined the new Composer and Packagist sponsorship program as a launch sponsor, supporting the team that keeps PHP's package ecosystem secure.
Research
/Security News
Benign-looking npm packages split malicious functionality across a dependency chain that deploys a cross-platform RAT targeting Alibaba developers.