System 1 MCP Server

A Jev-powered System 1 reflex engine for AI agents via Model Context Protocol (MCP).

In cognitive psychology (Daniel Kahneman's Thinking, Fast and Slow), intelligence operates on two systems:

• System 1: Fast, instinctive, calibrated subconscious reflexes (~100 ms).
• System 2: Slow, deliberative, logical, token-heavy conscious reasoning (~2–5 seconds).

Modern AI agents (Claude Desktop, Cursor, Antigravity, OpenHands, Hermes) currently lack System 1. They use heavy large language model deliberation for every single micro-decision—including trivial checks like "is this command destructive?", "did these tests pass?", or "which of these 3 files should I inspect?". This burns 1,500–3,000 ms of latency and hundreds of tokens per check.

System 1 MCP gives agents their missing reflex layer. Powered by TypeSafe's Jev model, System 1 MCP equips agents with 4 high-speed reflex tools (fast_guard, fast_judge, fast_verify, fast_score) that return typed probabilities and discrete verdicts in ~124 ms warm (~450–600 ms cold) without chain-of-thought token generation.

Executive Summary: TypeSafe provides the foundational model; System 1 MCP provides the agent runtime integration layer. It bridges raw classification heads into live agent workflows by packaging pre-calibrated safety batteries, enforcing fail-safe escalation, and automating single-command deployment across Claude Desktop, Cursor, Antigravity, and Windsurf.

What Changes When You Install System 1 MCP?

How the Agent Uses It (Lifecycle Walkthrough)

Once configured in your editor (via uvx system1-mcp install), the tools appear directly in the agent's MCP tool palette:

1. User prompt: "Clean up temporary build artifacts."
      │
      ▼
2. Agent proposes shell command: `rm -rf build/ dist/`
      │
      ▼
3. Agent automatically invokes MCP tool:
   `fast_guard(command="rm -rf build/ dist/", goal="clean artifacts")`
      │
      ▼  [TypeSafe Jev ~124ms warm / ~450–600ms cold]
4. System 1 MCP returns verdict:
   {"action": "block", "is_destructive": 0.98, "blast_radius": 1.0}
      │
      ▼
5. Agent halts execution, respects the reflex boundary, and requests user confirmation:
   "This command will forcefully delete build/ and dist/. Do you want to proceed?"

┌─────────────────────────────────────────────────────────┐
│                 Host AI Agent Loop                      │
│        (Claude Desktop / Cursor / Antigravity)          │
└───────────────────────────┬─────────────────────────────┘
                            │
              Calls MCP Tool (JSON-RPC stdio)
                            │
                            ▼
┌─────────────────────────────────────────────────────────┐
│                 System 1 MCP Server                     │
│  - fast_guard (safety & blast radius)                   │
│  - fast_judge (best-option selection)                   │
│  - fast_verify (assertion & goal validation)            │
│  - fast_score (spectrum & severity rating)              │
└───────────────────────────┬─────────────────────────────┘
                            │
             Single HTTP call to api.typesafe.ai
                            │
                            ▼
┌─────────────────────────────────────────────────────────┐
│             TypeSafe Jev (System One Model)             │
│   ~124ms warm keep-alive • Calibrated probabilities     │
└─────────────────────────────────────────────────────────┘

Latency Profile and Operational Model

• Model inference: ~20–40 ms
• Network round-trip to api.typesafe.ai: ~30–120 ms (geography dependent)
• Response Cache Hit: < 2 ms (in-memory memoization, SHA-256 canonical keys)
• Warm Keep-Alive Latency (p50): ~124.4 ms (p90: 162.2 ms, p99: 258.8 ms over persistent HTTP connection)
• Cold Start / Unpooled First Request: ~420–600 ms (TCP/TLS handshake floor; network spikes can take several seconds)
• Token Generation: Zero completion tokens required; state is classified directly via small specialized reflex models.

Advisory Notice: MCP tools provide advisory assessments. System 1 MCP supplies calibrated risk probabilities and classifications; the calling agent's decision engine retains authority over final execution.

Empirical Benchmark and Safety Evaluation

The following benchmark reflects live evaluation against TypeSafe Jev (jev-latest, recorded 2026-09-24, N=104 test cases across safe, dangerous, and ambiguous suites):

* Initial cold-start unpooled request incurs TCP/TLS handshake floor (~420–600 ms). Warm pooled HTTP keep-alive requests execute at sub-140 ms p50.

Full Latency & Safety Distribution (N=104 Eval Run)

Evaluation Methodology Footnote: Evaluated using scripts/eval_guard.py on 2026-09-24 against TypeSafe Jev (jev-latest). Tuned thresholds: block_threshold = 0.80, review_threshold = 0.40, destruct_block_threshold = 0.80, danger_block_threshold = 0.70, scope_review_threshold = 0.40. Full reproducible dataset recorded in tests/records_eval_run2.jsonl and summary in tests/eval_report_run2.json.

Tool Reference

1. fast_guard — Pre-Execution Command and Action Safety Check

Call prior to executing shell commands, database updates, or external API modifications to assess risk profile and blast radius.

Input:

{
  "command": "rm -rf /var/cache/*",
  "goal": "Clean project temporary artifacts",
  "workspace": "/repo"
}

Output:

{
  "action": "block",
  "is_destructive": 0.99,
  "is_dangerous": 0.72,
  "is_out_of_scope": 0.85,
  "blast_radius": {
    "score": 2.1,
    "legend": {
      "0": "Isolated: Read-only check, single temporary file, or no persistent side effects.",
      "1": "Workspace: Modifies multiple files, dependencies, or build artifacts within the local project directory.",
      "2": "System-wide: Modifies system configuration, global packages, root directories, or OS settings.",
      "3": "External: Impacts remote servers, production databases, external APIs, or network resources."
    }
  },
  "cache_hit": false
}

Decision Logic:

1. Danger Block: If is_dangerous >= 0.70 (or danger_block_threshold) ➔ "block".
2. Destruction Evaluation: If is_destructive >= 0.80 (or destruct_block_threshold):
   • If destruction is strictly workspace-contained (blast_radius <= 1.0) with low danger and goal alignment (p_out_of_scope < 0.40) ➔ "review" (e.g., rm -rf build/ dist/).
   • Otherwise (uncontained or out-of-scope destruction) ➔ "block".
3. High Blast Escalation: If blast_radius >= 2.0 (system-wide or external) with moderate risk (p_dangerous >= 0.40 or p_destructive >= 0.40) ➔ "block".
4. Moderate Risk: If max(is_destructive, is_dangerous) >= 0.40 ➔ "review".
5. Out of Scope with Read-Only Exemption: If is_out_of_scope >= 0.40 and (blast_radius >= 1.0 or is_destructive > 0.15) ➔ "review". Benign read-only exploration (git status, ls, cat) with blast_radius < 1.0 remains "pass".
6. Safe: Otherwise ➔ "pass".

2. fast_judge — Best-Option Selection

Select one option from a bounded set without deliberative text generation.

Input:

{
  "question": "Which configuration file handles TypeScript compiler options?",
  "options": {
    "tsconfig.json": "TypeScript configuration",
    "package.json": "NPM manifest",
    "vite.config.ts": "Bundler configuration"
  }
}

Output:

{
  "choice": "tsconfig.json",
  "confidence": 0.96,
  "probabilities": {
    "tsconfig.json": 0.96,
    "package.json": 0.03,
    "vite.config.ts": 0.01
  },
  "is_confident": true,
  "cache_hit": false
}

Large Candidate Sets (>20 Options):

• Jev-class models exhibit reduced discrimination when choosing among large candidate sets. When len(options) > 20, the response automatically includes a warning: "warning": "accuracy degrades with >20 options; consider staged elimination"
• Confidence on sets >20 is evaluated via top-1/top-2 margin rather than an absolute floor: is_confident is true iff p_top1 - p_top2 >= 0.30 (tunable via margin_threshold). For sets ≤20, the standard absolute confidence_floor (default 0.60) applies.

3. fast_verify — Condition and State Verification

Verify assertions against evidence, goal completion, test outputs, or status checks.

Input:

{
  "statement": "All unit tests passed without regression",
  "evidence": "PASSED tests/test_auth.py (14/14) in 1.2s. 0 failed, 0 skipped."
}

Output:

{
  "probability": 0.98,
  "is_true": true,
  "assessment": "high_confidence_yes",
  "cache_hit": false
}

Assessment Classifications:

• > 0.85 ➔ "high_confidence_yes"
• 0.60–0.85 ➔ "likely_yes"
• 0.40–0.60 ➔ "uncertain"
• 0.15–0.40 ➔ "likely_no"
• < 0.15 ➔ "high_confidence_no"

4. fast_score — Multi-Level Assessment

Evaluate inputs against an ordered scale (e.g., severity, priority, or alignment).

Input:

{
  "question": "Rate the severity of this production alert",
  "levels": [
    "Low / Cosmetic: non-blocking visual issue",
    "Medium: degraded feature with workaround available",
    "High / Critical: database unavailable or data corruption risk"
  ],
  "content": "ALERT: Primary PostgreSQL instance replication lag exceeded 15 minutes, writes failing."
}

Output:

{
  "score": 1.95,
  "confidence": 0.91,
  "legend": {
    "0": "Low / Cosmetic: non-blocking visual issue",
    "1": "Medium: degraded feature with workaround available",
    "2": "High / Critical: database unavailable or data corruption risk"
  },
  "probabilities": {
    "0": 0.01,
    "1": 0.08,
    "2": 0.91
  },
  "is_confident": true,
  "cache_hit": false
}

Response Caching & Memoization

Agents frequently re-evaluate identical commands or assertions in validation loops. System 1 MCP includes an in-memory response cache:

• Canonical Keying: Keyed on sha256(json.dumps({"backend": backend_name, "tool": tool_name, "inputs": normalized_inputs, "model": model_version, "thresholds": effective_thresholds}, sort_keys=True)).
• Backend Isolation: Incorporates serving backend (typesafe, local, auto) into the cache key so switching backends never serves a cross-backend cached response.
• Configurable TTL: Defaults to 300 seconds (5 minutes); configurable via cache_ttl_seconds in ~/.system1/config.json or SYSTEM1_CACHE_TTL environment variable.
• Latency: Cache hits return in < 2 ms.
• Cross-Process Diagnostics: system1-mcp doctor inspects persistent rolling hit/miss counters recorded in ~/.system1/cache_stats.json.

Pluggable Decision Backends & Local Fallback

System 1 MCP features a pluggable backend abstraction (DecisionBackend) supporting three execution strategies:

1. typesafe: Dispatches requests exclusively to the cloud TypeSafe API (api.typesafe.ai) for hosted Jev models (~124 ms warm).
2. local: Executes queries offline on local hardware using the Verdict Open-Jev ONNX build (~151M ModernBERT parameters) via CPU ONNX Runtime with zero PyTorch or CUDA dependencies.
3. auto (Default): Attempts the high-fidelity TypeSafe API first. If disconnected or unconfigured, it checks if local weights are present and allow_experimental_fallback is enabled. If disabled or unavailable, it emits a structured fallback_action: "escalate" response so the agent can fall back to standard reasoning.

Experimental Safety Evaluation Notice (Verdict Model)

To enable experimental fallback:

# Enable experimental local fallback via CLI
system1-mcp config set-experimental-fallback true

# Or set environment variable
export SYSTEM1_ALLOW_EXPERIMENTAL_FALLBACK=1

Universal Model-Weight Installation (models download)

Model weights are not bundled with the pip package to keep installs lightweight (~1.5 MB). Install local weights on-demand:

# Download and verify pinned Verdict model weights (~151M) to ~/.system1/models/verdict
system1-mcp models download

# Or opt-in during automated IDE configuration
system1-mcp install --with-local-model

• Universal Storage Path: Path.home() / ".system1" / "models" / "verdict" (C:\Users\<user>\.system1\models\verdict on Windows, ~/.system1/models/verdict on macOS/Linux).
• Resolution Order: --model-path flag > config.json local_model_path > SYSTEM1_LOCAL_MODEL_PATH env > ~/.system1/models/verdict.
• Atomic & Verified: Downloads model.onnx, tokenizer.json, and calibrator.json via HTTPS streaming with atomic temporary files. Skips download if the file already exists and matches hash.
• Cryptographic Supply-Chain Security: Strictly verifies SHA-256 of model.onnx against pinned hash 4ae01f822538b000fa0e55859d4b3e6b40871d860149397e8784428b2a42ee5e at both download time and load time.

Local Backend Model Specification

• Architecture: GLiClass / ModernBERT-base (answerdotai/ModernBERT-base, ~151M parameters)
• Repository Source: Pinned to heman10x/rlcd-modernbert-151m at revision 8af2496eb63c7fa66d7d234e1f62629380030eb4.
• Checkpoint Artifact: model.onnx (SHA-256: 4ae01f822538b000fa0e55859d4b3e6b40871d860149397e8784428b2a42ee5e).
• Dependencies: Pure CPU runtime via onnxruntime, tokenizers, and numpy (installable via pip install "system1-mcp[local]").

Backend Configuration

Configure backend mode, model path, and fallback behavior via CLI or ~/.system1/config.json:

# Set backend execution mode (auto | typesafe | local)
system1-mcp config set-backend auto

# Enable/disable experimental local fallback in auto mode
system1-mcp config set-experimental-fallback true

# Set custom directory containing model.onnx and tokenizer.json
system1-mcp config set-model-path /path/to/verdict

# Inspect backend status and local model readiness
system1-mcp doctor

Alternatively, configure via environment variables:

• SYSTEM1_BACKEND: Execution mode (auto, typesafe, or local)
• SYSTEM1_ALLOW_EXPERIMENTAL_FALLBACK: Set to 1 or true to permit fallback to experimental local models
• SYSTEM1_LOCAL_MODEL_PATH: Directory containing model.onnx and tokenizer.json (defaults to ~/.system1/models/verdict)
• SYSTEM1_CACHE_TTL: Cache entry time-to-live in seconds (defaults to 300)

Resilience and Graceful Escalation

When API errors, network timeouts, or rate limits occur and no local fallback model is available, System 1 MCP maintains standard MCP connection stability and does not terminate the JSON-RPC channel. Instead, it emits a structured fallback payload:

{
  "error": true,
  "error_type": "api_timeout",
  "message": "TypeSafe API request timed out after 5.0s",
  "fallback_action": "escalate"
}

When receiving fallback_action: "escalate", the host agent gracefully falls back to standard LLM deliberative reasoning.

Installation and Setup

Option A: Automatic Multi-IDE Installer (Recommended)

System 1 MCP includes an automated installer that detects and configures Claude Desktop, Cursor, Google Antigravity, Windsurf, Roo Code, Cline, and Zed:

# Interactive setup (prompts for API key and autodetects IDE installations)
uvx system1-mcp install

# Non-interactive setup with explicit key and local model download
uvx system1-mcp install --api-key ts_live_your_key_here --with-local-model

Option B: Health Check and Diagnostics (doctor)

Inspect installation status, identify detected configuration paths, verify local model readiness, and measure live API latency:

uvx system1-mcp doctor

Sample output:

⚡ System 1 MCP Diagnostics (v0.2.0)

Environment:
  Python:        3.11.15
  Config File:   ~/.system1/config.json (found)

API Key Status:
  Status:        ✅ Configured
  Resolved Key:  ts_...8f2a
  Source Origin: config_file

Live TypeSafe Jev Connectivity:
  Status:        ✅ Connected to api.typesafe.ai
  Model:         jev-1.13.0
  Roundtrip:     ⚡ 124.4ms
  Calibration:   P(valid) = 0.99

Decision Backend Status:
  Configured Mode:       auto
  Experimental Fallback: Disabled (safe default)
  Local Model:           ✅ Ready (CPU ONNX)
  Model Path:            ~/.system1/models/verdict

Detected IDE Configurations:
  Claude Desktop       [Detected     ] -> Configured ✅
  Cursor               [Detected     ] -> Configured ✅
  Google Antigravity   [Detected     ] -> Configured ✅

Response Cache Status:
  Hits:          42
  Misses:        5
  Hit Ratio:     89.4%
  Cache TTL:     300s

Option C: Manual Configuration

To manually configure an editor, add the server configuration entry:

Claude Desktop (claude_desktop_config.json) / Antigravity (mcp_config.json) / Cursor

{
  "mcpServers": {
    "system1": {
      "command": "uvx",
      "args": ["system1-mcp"],
      "env": {
        "TYPESAFE_API_KEY": "your-typesafe-api-key-here"
      }
    }
  }
}

Note: If your key is stored in ~/.system1/config.json, the "env" block is optional; the server resolves stored credentials automatically.

Configuration Hierarchy

System 1 MCP searches for credentials using the following resolution order:

1. Process Environment: TYPESAFE_API_KEY (from environment or host IDE env map)
2. User Configuration: ~/.system1/config.json (with fallback to ~/.fastpath/config.json)
3. Workspace File: .env in the current working directory

To configure stored user credentials via CLI:

# Store API key
uvx system1-mcp config set-key ts_live_your_key_here

# Display current configuration status
uvx system1-mcp config show

Agent Instructions (AGENTS.md / .cursorrules / CLAUDE.md)

MCP registers the reflex tools in your IDE, but adding an explicit instruction to your project ensures your agent invokes them automatically rather than relying on slow text deliberation.

Copy and paste the following snippet into your repository's AGENTS.md, CLAUDE.md, or .cursorrules:

# System 1 Reflex Rules
You have access to System 1 MCP tools (`fast_guard`, `fast_judge`, `fast_verify`, `fast_score`).
1. Pre-Execution Safety: Call `fast_guard(command, goal)` before running shell commands or modifying databases. If action == "block", halt immediately and alert the user.
2. Option Arbitration: Call `fast_judge(question, options)` when choosing among candidate files or configurations instead of reading entire files into context.
3. Verification: Call `fast_verify(statement, evidence)` with terminal output to confirm test passes or deployment health.

See AGENTS.md in this repository for the full reference implementation.

Development and Testing

# Run unit test suite (65+ offline unit tests)
pytest tests/ -v -m "not integration"

# Run integration tests against the live TypeSafe Jev API (requires TYPESAFE_API_KEY)
pytest tests/test_integration.py -v -m integration

Architectural Comparison

License

This project is licensed under the terms of the MIT License.