Architecture

Architecture

security-mcp is a single local process that speaks the Model Context Protocol. Your editor or CI runner is the client; the server holds the engines. Nothing is hosted, and your source stays on your machine. This page covers the major components, how they connect, and exactly what the tool writes into a project.

System overview

flowchart TB
  subgraph Client[Editor or CI]
    CC[Claude Code / Cursor / VS Code / Windsurf]
    CI[CI runner]
  end

  subgraph Server[security-mcp server]
    Auth[Caller auth]
    Tools[MCP tools + prompts]
    Gate[Gate engine]
    Cloud[Cloud controls engine]
    Orch[Orchestrator runtime]
    Router[Model router]
    Learn[Learning engine]
    Chain[Attestation chain]
  end

  subgraph Intel[Optional egress, permission-gated]
    KEV[CISA KEV]
    EPSS[EPSS]
    OSSF[OpenSSF Scorecard]
    NPM[npm registry]
  end

  CC -->|stdio MCP| Auth
  CI -->|ci:pr-gate| Gate
  Auth --> Tools
  Tools --> Gate
  Tools --> Orch
  Gate --> Cloud
  Gate --> Intel
  Orch --> Router
  Orch --> Learn
  Gate --> Chain
  Orch --> Chain
  Gate --> Disk[(.mcp/ artifacts)]
  Orch --> Disk

Loading

The client connects over stdio. The optional shared-secret caller auth layer sits in front of the tool surface. The tools drive the engines, and the engines write their results into the project's .mcp/ directory.

The gate engine

The gate is the deterministic core. It loads policy, scopes the change, classifies what kind of code it is looking at, runs 35 checks in parallel, reconciles findings against exceptions and a baseline, scores confidence, and returns a verdict. It is the same engine whether it runs from the editor, from ci:pr-gate, or from inside an agent. Full detail lives in The Gate Engine.

flowchart LR
  P[Load policy] --> S[Scope change] --> C[Classify + detect surfaces]
  C --> Checks[35 parallel checks]
  Checks --> SLA[SLA + coverage manifest]
  SLA --> Ex[Apply exceptions]
  Ex --> Conf[Confidence score]
  Conf --> Base[Baseline regression diff]
  Base --> V{Verdict}
  V --> Persist[Persist baseline]

Loading

The orchestrator

The orchestrator runtime coordinates a multi-agent program: leads spawn sub-agents, agents pull skills on demand from a 91-skill registry, and findings are merged, deduplicated, and synthesized into a compliance report and attestation. Agents have persistent memory and self-heal behavior, and routing is informed by historical run outcomes. See CISO Orchestrator.

Supporting subsystems

flowchart TB
  subgraph Router[Model router]
    R1[Cost-aware task routing]
    R2[Circuit breaker: 3 fails, 60s cooldown]
    R3[Budget tracking, default $5]
    R4[Provider health]
  end
  subgraph Learn[Learning engine]
    L1[Integrity-checked pattern memory]
    L2[False-positive rate limiting]
    L3[ISO 42001 routing audit]
  end
  subgraph Chain[Attestation chain]
    A1[Genesis block]
    A2[HMAC or SHA-256 linked blocks]
    A3[Constant-time verify]
  end
  subgraph CAuth[Caller auth]
    K1[Shared-secret HMAC]
    K2[3-strike lockout]
    K3[Session TTL 8h, max 24h]
  end

Loading

• Model router. Multi-provider and cost-aware. It selects the right model per task, tracks spend against a default $5 budget, monitors provider health, and trips a circuit breaker after 3 consecutive failures with a 60 second cooldown. It is model-agnostic: bring whatever provider your MCP client is configured with.
• Learning engine. Records outcomes into an integrity-checked pattern store, rate-limits false positives so noisy findings do not repeat, and keeps an ISO 42001 style audit of routing decisions.
• Attestation chain. A tamper-evident hash chain. It opens with a genesis block, links each block with HMAC or SHA-256, and verifies in constant time. Attestation refuses to sign anything that is not a clean PASS.
• Caller auth. When SECURITY_MCP_SHARED_SECRET is set, callers authenticate with a constant-time HMAC handshake. Secrets must be at least 32 bytes, three failed attempts lock the caller out, and sessions expire after a default 8 hours, capped at 24.

What gets written to a project

All durable output lands under .mcp/ in the repo. This is the audit surface, and it is designed to be committed or archived.

Path	Contents
.mcp/policies/	The active security policy (default security-policy.json) and its optional .hmac signature sidecar
.mcp/exceptions/	Time-boxed, approved exceptions with their signatures
.mcp/reviews/	Review records from start_review: scope, findings, status
.mcp/reports/	Generated compliance reports and SHA-256 attestations for audit
.mcp/agent-runs/	Per-agent run state, findings, and persistent agent memory
.mcp/baselines/	The accepted-finding baseline used for regression diffing

Data at rest is written with 0o600 permissions. The baseline is what makes the gate stable over time: it records the set of findings already triaged so the gate can flag a regression (new HIGH or CRITICAL relative to baseline) as a hard failure while not re-failing on known, accepted items. See Configuration and Policy and Security and Hardening.