Introduction

Installation

Mainspring runs as a local MCP server over stdio. The normal user path is the npm package: install the CLI, let it create local config/data/log folders, then point your MCP client at the mainspring command.

# 1. Install the MCP server CLI
npm install -g mrmainspring

# 2. Create local config and print the MCP snippet
mainspring setup claude
# or: mainspring setup cursor

Paste the printed JSON into your MCP client configuration. The same command works for Claude Desktop, Cursor, or any MCP-compatible host:

{
  "mcpServers": {
    "mainspring": {
      "command": "mainspring"
    }
  }
}

# Check what Mainspring will use locally
mainspring doctor

# Optional advanced setup
mainspring init
mainspring config

For Casper anchoring during development, use the testnet — anchors are free and the contract behavior is identical to mainnet.

Quickstart

Once the MCP server is connected, your agent can call Mainspring tools directly. The local user path is: write a memory, get a deterministic receipt, then verify the hash. Casper submission stays pending unless you explicitly configure real testnet anchoring.

{
  "agent_id":  "atlas-treasury-02",
  "type":     "decision",
  "source": { "tool": "price_oracle", "symbol": "CSPR" },
  "body": {
    "action":    "TRANSFER 12400 CSPR",
    "rationale": "Rebalance to 30% stable reserve after weekly inflow."
  },
  "anchor": true
}

{
  "memory_id":     "mem_4f2c8e1a-...",
  "content_hash":  "9f3c4a71e0b2...",  // SHA-256 of full envelope
  "metadata_hash": "b8e109d2fa31...",  // SHA-256 of identity fields
  "anchor_status": "pending",           // local default until Casper is configured
  "anchor_id":    "c7f8a0e3..."
}

That receipt is a verifiable handle. Hand the content_hash to any counterparty; they can recompute it independently from the same envelope. With Casper testnet anchoring configured, the same hash-only proof can also be checked against the transaction record.

The Loop

Every decision runs the same clock. Mainspring is built like a watch — four movements that only mean something when they turn together.

• Act — your agent decides and acts on available data.
• Witness — Mainspring meters the decision at the source, hashing the full envelope before it can be altered.
• Anchor — the content hash and anchor id are submitted to Casper via casper-client, creating an immutable on-chain record.
• Prove — anyone can recompute the hash from the stored envelope and verify it against the chain, independently, without trusting Mainspring.

Memory Envelope

Every memory written to Mainspring is serialized into a MemoryEnvelope before hashing. The schema is versioned and deterministic — the same inputs always produce the same hash.

Canonical JSON sorts all object keys alphabetically at every depth level and omits undefined values. This guarantees the same input always produces the same hash regardless of the serializer used.

The prev_anchor_hash field chains attestations together. When a memory is anchored, its anchor_id is stored as the previous hash for the agent's next anchored write — creating a verifiable chain of custody.

Witnesses

A witness is the MCP server running alongside your agent. It is the sole trusted observer — it receives the raw decision data, computes the hash before any transmission can alter it, and dispatches the anchor submission.

The witness is non-blocking. Anchoring runs asynchronously — anchor_status: "pending" is returned immediately; the status transitions to "anchored" once casper-client confirms the transaction. If the anchor call fails, the memory is still stored locally with anchor_status: "failed" — no data is lost.

The witness never touches body content for anchoring — it only sees the hash. Body data stays in local storage (file or Supabase) and never reaches Casper.

memory.read · search · verify

Three read-path tools that cover retrieval, discovery, and integrity verification.

{
  "valid":               true,
  "stored_hash":         "9f3c4a71e0b2…",
  "computed_hash":       "9f3c4a71e0b2…",
  "hashes_match":        true,
  "onchain_content_hash": "9f3c4a71e0b2…"  // present if anchored
}

Grimoire

The Grimoire is Mainspring's encrypted vault for secrets and spending policies. It provides two sub-systems: secret storage (AES-256-GCM) and policy enforcement for the x402 payment flow.

Secrets

Secrets are encrypted with AES-256-GCM using a 12-byte random nonce. The plaintext is never returned by any MCP tool — not even in confirmations. If you lose the plaintext, it is gone.

Policies

Policies gate x402 payment operations. Every payment.fetch call runs a policy check first — no payment proceeds without an active, matching policy.

{
  "policy_id":             "pol_cspr_transfers",
  "enabled":              true,
  "allowed_urls":          ["https://api.example.com/data"],
  "allowed_methods":       ["GET"],
  "max_amount_per_call":   "0.05",
  "max_amount_per_period": "1.00",
  "period_seconds":        86400
}

Policy denial reasons: policy_not_found · policy_disabled · url_not_allowed · method_not_allowed · amount_over_limit · invalid_amount. Each reason is audited.

Payments

Mainspring implements the x402 payment protocol — a three-stage state machine for policy-gated, challenge-based micropayments over HTTP. Each stage advances the same PaymentIntent record.

Not yet implemented: real Casper x402 signed payload, paid retry to the resource, and facilitator settlement verification. The DisabledX402SettlementProvider always returns settlement_unavailable. Both CASPER_ENABLE_REAL_SUBMISSION and X402_ENABLE_REAL_SETTLEMENT are explicit opt-in gates — they never default to true.

Use payment.receipt to read a payment intent at any stage — it returns the full record including status, denial reason, and challenge requirements.

Audit

audit.tail returns the most recent audit events across all services. Every tool call that writes state records an event automatically — no opt-in required.

{ "limit": 20 }  // default: 20, max: 100

All audit metadata is sanitized before storage. Keys matching secret, token, key, password, private, payload, credential, authorization, or value are automatically redacted to [REDACTED]. Max depth: 6, max string: 2 048 chars, max total event size: 16 KB.

Storage Backends

Both backends implement identical interfaces. The choice is made at startup via SIGIL_STORAGE_BACKEND — no code changes required to switch.

Security Model

CLI arguments passed to casper-client are validated against /^(hash-)?[a-f0-9]{64}$/i before the process is spawned. This prevents command injection via malformed hash strings in any stored data.

The grimoire master key is intentionally excluded from all storage backends, audit logs, and MCP responses. If GRIMOIRE_MASTER_KEY is absent at startup, Mainspring generates one automatically for local use; keep production secrets in a private env file.

FAQ