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. A plain GET /api/mcp opens a server-sent events stream and may appear to hang. To make a JSON-RPC call, send a POST request like the curl example below. If your client can't attach a custom MCP server (some hosted assistants block or limit remote MCP connectors), the curl quickstart runs the same sandbox verification over plain HTTP with no account.

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"}}}'

Integration expectations

Typical verification takes one to two seconds, including the signed receipt. Design asynchronous flows for clients with tight timeouts. Submissions are idempotent, so if a response is ambiguous, replay the same request instead of signing a fresh one. A signed receipt never means payment was authorized.

Run the server

Run the published npm package with npx @spoolis/mcp, or use npm run mcp from this repository. The server is listed on the official MCP Registry as com.spoolis/mcp, so registry-aware clients can discover it by name. Without an API key, the server starts in demo mode against https://spoolis.com. Set SPOOLIS_BASE_URL to override the sandbox host. With SPOOLIS_API_KEY, SPOOLIS_API_URL defaults to https://spoolis.com; set it to http://localhost:3000 for local development.

npx @spoolis/mcp
npm run mcp
SPOOLIS_API_KEY=spk_live_example npx @spoolis/mcp

Configure Claude Code

Add a stdio server that runs the npm package. Add the environment block only for authenticated mode.

{
  "mcpServers": {
    "spoolis": {
      "command": "npx",
      "args": ["-y", "@spoolis/mcp"],
      "env": {
        "SPOOLIS_API_KEY": "spk_live_example",
        "SPOOLIS_API_URL": "https://spoolis.com"
      }
    }
  }
}

Configure Cursor

Cursor accepts the same stdio command shape in its MCP configuration.

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

Call verify_result first

verify_result takes criteria, evidence, unit economics, and a chosen judge or check path, then returns a durable acceptance result: accepted, rejected, and uncertain units, earned value, reasons, and a signed Outcome. Before acting on that Outcome later, call get_receipt_status to confirm it is still current.

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"demo","version":"1.0.0"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"verify_result","arguments":{"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"}}}}' \
  | npx @spoolis/mcp

The MCP text result contains JSON with spool_id, earned_cents, accepted, rejected, rejections with unit and reason, receipt, receipt_url, verification_run_id, terminal, settlement_eligible, can_resubmit_evidence, can_rerun, next_step, and decision_authority. This example returns 2 accepted, 1 rejected, and 2 cents earned.

Tools

verify_result is first. It creates an inspectable unilateral Spool. The external provider is identified but does not accept the criteria in Spoolis.

The other 31 tools support the bilateral lifecycle when both parties need to accept inside Spoolis.

Most developers should start with verify_result; the bilateral tools are for workflows where both sides need to agree inside Spoolis.

MCP is the recommended default path for agents; the REST API is the full-control path with the same conceptual lifecycle, and neither replaces the other. In the no-key sandbox, use compile_spool to create a proposed draft, get_spool and get_spool_events to inspect it, amend_spool to change its conditions or unitization before confirming, accept_spool to confirm the contract, and abandon_spool to clean up an active Spool before settlement is committed. The same conceptual tools target production when an API key is configured. Each tool description states whether it works in the sandbox or is production only.

Spoolis maintains the acceptance state around the chosen judgment, determines what counted and what was earned, and signs the Outcome Receipt. A wallet, marketplace, payment system, or configured integration may verify and consume it, then act under its own authorization and settlement policy.

Offline signature verification proves authenticity without Spoolis uptime. The optional status check uses GET /api/v1/receipts/{receipt_id}/status and only adds correction, revocation, or advisory state. In demo mode, tools with sandbox equivalents label their results as demo.

Keep your own judge

Conditions judged by your own system (CI, a marketplace evaluator, buyer-owned telemetry) use the external evaluator interface: the judge stays yours, and Spoolis standardizes the result into the signed Outcome. See Bring your own judge.

Evidence-aware results

Structured Spools can declare per-condition evidence requirements. Verification reports whether each required item is present, missing, stale, unavailable, or fails its provenance constraint. Missing required evidence defaults the criterion to uncertain. Unitized receipts can also publish salted per-unit identifiers without exposing the per-Spool salt.