Clearlist for AI agents

MCP server

@clearlist/mcp is a stdio server built on the official MCP SDK. It needs CLEARLIST_API_KEY and optionally CLEARLIST_BASE_URL. A test key (cl_test_…) is unlimited and free; use a live key when the agent acts for real users so the decisions count toward your evidence trail.

Claude Code

claude mcp add clearlist -e CLEARLIST_API_KEY=cl_test_… -- npx -y @clearlist/mcp

Claude Desktop and Cursor

Add this to claude_desktop_config.json (Settings, Developer, Edit Config) or to .cursor/mcp.json:

{
  "mcpServers": {
    "clearlist": {
      "command": "npx",
      "args": ["-y", "@clearlist/mcp"],
      "env": { "CLEARLIST_API_KEY": "cl_test_…" }
    }
  }
}

Tools

Source and smoke test in packages/mcp. The server depends on nothing but the MCP SDK and calls the REST API with fetch.

x402 pay-per-screen

x402 is the HTTP 402 payment protocol: the server answers an unpaid request with the price and a pay-to address, the client signs a USDC transfer authorisation and retries with it in a header, the server verifies and settles it through a facilitator, and the paid response carries the settlement receipt. No account, no key, no card. Clearlist charges $0.02 per screen in USDC on Base (eip155:8453) or Base Sepolia (eip155:84532) for testing.

The endpoint is POST https://clearlist.xyz/api/x402/screen. The body is exactly the POST /screen body (any subject type, plus optional idempotency_key and metadata). Decisions are persisted under Clearlist's x402 organisation with metadata.payer and metadata.network, so the receipt and the evidence stay linked. Speaks x402 v2 (PAYMENT-REQUIRED / PAYMENT-SIGNATURE / PAYMENT-RESPONSE) and accepts the v1 X-PAYMENT header.

The flow, with curl

1. Ask without paying. You get a 402 whose body (and base64 PAYMENT-REQUIRED header) says what to pay:

curl -i -X POST https://clearlist.xyz/api/x402/screen \
  -H 'content-type: application/json' \
  -d '{"type":"address","address":"0x098B716B8Aaf21512996dC57EB0615e2383E2f96"}'

{
  "x402Version": 2,
  "resource": {
    "url": "https://clearlist.xyz/api/x402/screen",
    "description": "Clearlist sanctions and risk screen: one decision …",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "20000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0xYourPayToAddress",
      "maxTimeoutSeconds": 60,
      "extra": {
        "name": "USDC",
        "version": "2",
        "assetTransferMethod": "eip3009"
      }
    }
  ]
}

2. Sign the exact payment for amount atomic units (20000 = $0.02 at six decimals) to payTo and retry with it. Bad input is rejected with a 400 before anything is charged; the screen runs before settlement, so a failed screen is never charged either:

# PAYMENT-SIGNATURE is the base64 JSON payment payload your x402 client signs
# from the `accepts[0]` requirements above (an EIP-3009 transferWithAuthorization).
curl -i -X POST https://clearlist.xyz/api/x402/screen \
  -H 'content-type: application/json' \
  -H "PAYMENT-SIGNATURE: $PAYMENT" \
  -d '{"type":"address","address":"0x098B716B8Aaf21512996dC57EB0615e2383E2f96"}'

# 201 Created
# PAYMENT-RESPONSE: eyJzdWNjZXNzIjp0cnVlLCJ0cmFuc2FjdGlvbiI6IjB4…   (base64 { success, transaction, network, payer })
# { "id": "dec_…", "outcome": "block", "reasons": [ … ], "lists": { … }, "metadata": { "payer": "0x…", "network": "eip155:8453" } }

In code, an x402 client does the 402, sign, retry loop for you:

import { x402Client, wrapFetchWithPayment } from "@x402/fetch";   // or any x402 v2 client
import { ExactEvmScheme } from "@x402/evm/exact/client";

const client = new x402Client().register("eip155:8453", new ExactEvmScheme(signer));
const fetchWithPay = wrapFetchWithPayment(fetch, client);

const res = await fetchWithPay("https://clearlist.xyz/api/x402/screen", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ type: "address", address: "0x098B716B8Aaf21512996dC57EB0615e2383E2f96" }),
});
const decision = await res.json();   // the 402 → pay → retry loop happened inside fetchWithPay

A GET on the same URL also returns the 402 so an agent can read the price without composing a body. Invalid or underpaid payments get a fresh 402 with an error; a facilitator outage is a 502 with nothing charged.

Running it yourself

The route answers 503 until it is configured. Environment:

Verification and settlement call the facilitator's REST API directly (POST /verify, POST /settle) rather than through @x402/next, so the payer can be attached to the decision before settlement and the 402 shape is unit-tested with fixtures.