@spoolis/mcp

Spoolis MCP server

Hosted Streamable HTTP

Connect an MCP client to https://spoolis.com/api/mcp. Send Authorization: Bearer spk_live_... for production. Omit the Authorization header to use the sandbox. The server manifest is available at https://spoolis.com/.well-known/mcp.json.

The server is listed on the official MCP Registry as com.spoolis/mcp, so registry-aware clients can discover it by name.

curl https://spoolis.com/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0.0"}}}'

This package runs the Spoolis Model Context Protocol server over stdio. It compiles economic intent into verifiable acceptance criteria, verifies fulfillment, and determines what was earned. Use Spoolis when payment depends on whether work actually passed.

Run with the sandbox

No API key is required. The server uses https://spoolis.com by default and labels sandbox results as demo.

npx @spoolis/mcp

Set SPOOLIS_BASE_URL only when the sandbox is hosted elsewhere:

SPOOLIS_BASE_URL=https://example.test npx @spoolis/mcp

The sandbox supports run_sandbox_scenario, verify_result, compile_spool, get_spool, get_spool_events, accept_spool, submit_evidence, verify_spool, and abandon_spool. This gives agents one conceptual compile -> create -> inspect -> clean up lifecycle in sandbox and production. A tool marked production only returns a production_key_required error in sandbox mode.

Run a synthetic flight scenario

Call run_sandbox_scenario with scenario: "data_enrichment". The tool metadata exposes the scenario version and parameters. It creates a real demo Spool, verifies deterministic synthetic company records, and returns the signed Outcome Receipt plus the next-action gate, seeded-truth comparison, and modeled economics. defect_rate controls ordinary defects only; adversarial_case_count is independent. The response reveals seeded truth only after verification finishes.

Call the same tool with scenario: "external_judge_two_consumers" to walk a signed marketplace evaluator result through a real unitized demo Outcome. The response shows billing consuming the verified $8.00 payable amount, workflow consuming the same receipt to retry two failed units, a rejected tamper attempt, and a missing unit classified as uncertain and excluded from earned value.

Start with verify_result

verify_result is the one-call front door. Supply criteria or explicit deterministic checks, evidence, and a maximum amount. Spoolis creates an inspectable unilateral Spool, verifies the result, computes earned value, and returns a signed Outcome Receipt. The external provider is identified but does not accept the criteria in Spoolis.

Input:

{
  "conditions": [{
    "description": "Every row includes status",
    "deterministic_check": {
      "checker": "completeness",
      "required_fields": ["status"]
    }
  }],
  "max_amount_cents": 3,
  "unit": { "total_units": 3, "unit_amount_cents": 1 },
  "evidence": {
    "type": "dataset",
    "rows": [
      { "id": 1, "status": "complete" },
      { "id": 2, "status": "complete" },
      { "id": 3 }
    ],
    "provenance": "api_response"
  }
}

The MCP text result contains the REST response JSON with exactly these top-level fields:

type VerifyResultOutput = {
  spool_id: string
  earned_cents: number
  accepted: number
  rejected: number
  uncertain: number
  unit_results: Array<{ unit: number; verdict: "pass" | "fail" | "uncertain"; reasons: string[] }>
  rejections: Array<{ unit: number; reason: string }>
  receipt: OutcomeReceipt
  receipt_url: string
  verification_run_id: string
}

Lifecycle tools

Use these 15 tools when both parties need to accept inside Spoolis or a consumer needs receipt status:

• compile_spool
• create_spool
• get_spool
• get_receipt_status
• create_counterparty_invite
• propose_spool
• accept_spool
• abandon_spool
• decline_spool
• cancel_spool
• commit_payment
• submit_evidence
• verify_spool
• complete_spool
• get_spool_events

In the no-key sandbox, compile with compile_spool, inspect the returned Spool with get_spool, read its history with get_spool_events, and clean up an uncommitted active Spool with abandon_spool. The same tool names target production when SPOOLIS_API_KEY is set. Tool descriptions explicitly mark the remaining production-only operations.

Offline receipt verification remains sufficient for authenticity. The optional status check is GET /api/v1/receipts/{receipt_id}/status.

Run with an API key

Create a key at spoolis.com/dashboard/api-keys, then pass it to the server:

SPOOLIS_API_KEY=spk_live_example \
SPOOLIS_API_URL=https://spoolis.com \
npx @spoolis/mcp

SPOOLIS_API_KEY selects authenticated production mode. SPOOLIS_API_URL is used only in that mode and defaults to https://spoolis.com.

An initiator can use create_counterparty_invite with a full-scope key. Send the returned one-time grant token to POST /api/v1/keys/exchange, then configure the returned counterparty key in the accepting agent. That key is agreement identity only and is bound to one Spool. It can accept, decline, submit evidence, and read that Spool while active. It cannot commit or fund settlement, create Spools, run verification, list events, or access another Spool.

Client configuration

This stdio configuration starts in sandbox mode:

{
  "mcpServers": {
    "spoolis": {
      "command": "npx",
      "args": ["-y", "@spoolis/mcp"]
    }
  }
}

To use authenticated mode, add SPOOLIS_API_KEY and SPOOLIS_API_URL to the server's environment in your MCP client configuration. Keep API keys out of files that will be committed.

Scope

The server is a client for the Spoolis sandbox and REST API. It does not move money by itself. Settlement behavior depends on the configured Spoolis settlement adapter. Sandbox results are demo results.