@spoolis/mcp

Spoolis MCP server

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 compile_spool, accept_spool, submit_evidence, and verify_spool. Authenticated production mode also exposes abandon_spool for either party before settlement is committed. A tool without a sandbox equivalent returns a production_key_required error. In the canonical example, a buyer pays for 100 enrichment records at $1.00 per accepted record. Spoolis accepts 98, rejects 2 with reasons, and signs an Outcome Receipt for $98.00 earned. Follow the order compile, verify, receipt, verifyReceipt, optional GET /api/receipts/{id}/status, then act on earned. Offline signature verification remains sufficient.

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.