Spoolis
Verify work against acceptance criteria; signed receipts attest what passed and was earned.
Open source Open in the app JSON README (API)
About
Verify work against acceptance criteria; signed receipts attest what passed and was earned.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- com.spoolis
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.1.7
- Added
- 2026-08-31 20:00:08
- Updated
- 2026-09-04 13:00:54
- Origin id
com.spoolis/mcp
README
# 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.
```sh
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.
```sh
npx @spoolis/mcp
```
Set `SPOOLIS_BASE_URL` only when the sandbox is hosted elsewhere:
```sh
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:
```json
{
"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:
```ts
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](https://spoolis.com/dashboard/api-keys), then pass it to the server:
```sh
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:
```json
{
"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.