@curless/mcpbuyer

Buyer-side Curless payment tools. Mount them in any MCP server, agent, or skill to initiate and verify payments against the Curless platform.

This is the buyer/orchestration half. To charge for your own tools (seller side), use @curless/mcp's CurlessPaywall.

Install

npm install @curless/mcpbuyer

Use

import { curlessPaymentTools } from '@curless/mcpbuyer'

const tools = curlessPaymentTools({
  apiKey: process.env.CURLESS_SECRET_KEY!,        // merchant secret
  agentToken: () => readAgentTokenFromSession(),  // the spending principal
})

// Each entry is { descriptor, handler } — wire into whatever MCP server you run:
for (const t of tools) {
  myServer.registerTool(t.descriptor.name, t.descriptor.inputSchema, t.handler)
}

agentToken accepts a string, a resolver function, or omit it and let callers pass agent_token in the tool args.

Tools

| Tool | Caller | Purpose | |---|---|---| | curless_create_payment_session | merchant | Lock an amount → ps_… id (hand the id, not the amount, to the agent) | | curless_charge | agent | Create + auto-capture a charge (by session_id or amount). Returns next_action | | curless_get_charge_status | either | Confirm-authority — the only call that asserts credited from a real ledger entry |

The contract (obey next_action)

curless_charge returns a next_action: COMPLETE, EXEC_CAPTURE, AWAIT_APPROVAL, WAIT_FOR_CONFIRM, WAIT_FOR_WEBHOOK, or STOP.

Cardinal rule: a charge response is not proof of payment. Read credited: true from curless_get_charge_status (or the intent.succeeded webhook) before telling the user "paid".

Zero-dependency discovery

The canonical tool definitions are also served over HTTP — no install needed:

curl https://backend-omega-steel-11.vercel.app/v1/integrations/tools