Paycheck MCP Server

PayCheck

PayCheck scores whether a domain, an https URL, or a 0x wallet is safe to pay before an autonomous agent sends money.

It is part of the Toolweather suite, in the same family as Toolweather MCP health, Upstream, and SpendGate. SpendGate is for spend limits. PayCheck is only the payee trust check. It does not send payments, does not sign transactions, and does not hold wallet keys. A Toolweather bundle can front this API later with x-tw-bundle-secret and x-tw-bundle-client.

The score is deterministic. amount_usd, category, and any purpose text are discarded. Rewording them cannot fish for a better verdict.

When to use it

Call PayCheck once per payee, immediately before a checkout, invoice, or transfer.

• Use check_merchant for a domain (api.openai.com), an https URL, or a 0x address with 40 hex characters.
• Use get_quota to see how many free checks are left today.
• Use get_api_key once to mint a free pc_live_… key. Do not call it every turn.

Do not use PayCheck to send money, to hold keys, or to overturn a block by asking again with a friendlier category.

Scoring (policy v1)

Full rules, the allowlist, and the penalty table: GET /v1/policy (or http://127.0.0.1:8791/v1/policy locally).

Start at 100 and subtract penalties. policy_version is "1".

trusted is only for the published allowlist (about 40 known AI and developer API hosts, including openai.com, anthropic.com, stripe.com, github.com, cloudflare.com, vercel.com, and supabase.com). A brand-new or random domain is never trusted.

Recommended actions: proceed, verify_out_of_band, require_human_review, do_not_pay.

Domain age uses public RDAP (https://rdap.org). Successful lookups are cached in D1 for 7 days. Failures are cached for 24 hours.

Free tier

The same caller and the same target are idempotent for 60 seconds and do not consume a second free check.

Not billed: get_quota, get_api_key, GET /v1/policy, GET /health, docs, and MCP discovery.

Key minting is capped at 10 keys per IP per UTC day. PayCheck stores only a SHA-256 hash of the key.

x402 overage

Over-cap checks cost $0.001 USDC (1000 atomic units) on Base (eip155:8453), scheme exact, asset 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913, facilitator https://facilitator.payai.network.

PAY_TO is the receiving address. It is a Worker secret. If it is unset, over-cap calls return HTTP 402 with error: "payment_not_configured" and nothing is charged.

Bundle auth: header x-tw-bundle-secret must equal the Worker secret BUNDLE_PROXY_SECRET, and x-tw-bundle-client identifies the end caller.

API

MCP protocol versions: 2025-06-18 and 2025-03-26. Stateless JSON responses (no session). GET /mcp returns 405.

Tools:

1. check_merchant — may write check history. readOnlyHint: false, idempotentHint: true, openWorldHint: true, destructiveHint: false.
2. get_quota — free. readOnlyHint: true, idempotentHint: true.
3. get_api_key — free, mints a key. Not read-only. Do not call every turn.

curl -s -X POST http://127.0.0.1:8791/v1/check \
  -H 'content-type: application/json' \
  -d '{"target":"https://api.openai.com"}'

{
  "mcpServers": {
    "paycheck": {
      "type": "http",
      "url": "https://paycheck.toolweather.workers.dev/mcp"
    }
  }
}

Glama stdio entry, after npm run build:

node dist/stdio.js

The stdio process speaks newline-delimited JSON-RPC (one JSON object per line) and also accepts Content-Length frames on input. Its quota and keys are in memory. Production persistence is the Worker.

Local

npm install
npx wrangler d1 migrations apply paycheck --local
npm run dev
npm test
npm run typecheck

npm run dev serves the API and the landing page on port 8791.

Optional .dev.vars (gitignored; see .dev.vars.example):

# PAY_TO=0xYourReceivingAddress
# BUNDLE_PROXY_SECRET=replace-with-a-long-random-string

Deploy

Production lives at paycheck.toolweather.workers.dev. wrangler.toml already has the production D1 database_id. PAY_TO and BUNDLE_PROXY_SECRET are Worker secrets. Do not put them in [vars] or in git.

npx wrangler d1 migrations apply paycheck --remote
npx wrangler secret put PAY_TO
npx wrangler secret put BUNDLE_PROXY_SECRET
npx wrangler deploy

Check the bundle without deploying:

npm run dry-run

Layout

• src/score.ts — pure scorer, covered by unit tests
• src/http.ts — Hono routes
• src/mcp.ts — streamable HTTP JSON-RPC
• src/stdio.ts — Glama stdio entry (dist/stdio.js)
• migrations/ — D1 schema
• public/ — landing page
• lhm.plugin.json, glama.json — directory listing metadata

License

MIT. See LICENSE.