@curless/mcp-server

MCP server that lets any local AI agent (Claude Desktop, Cursor, Cline, LangChain, custom Python script, …) drive a Curless wallet + virtual card to order coffee, book hotels, and buy office supplies through real merchant endpoints.

v0.1 = single-user demo mode. Every install shares the same demo backend wallets. No real money — all charges are simulated. v0.2 introduces per-user API keys and real on-chain USDC.

What you get

18 MCP tools that wrap the Curless REST API:

| Category | Tools | |---|---| | VCC | create_vcc, top_up_vcc, update_vcc_limit, get_vcc_info | | Wallet | get_wallet_info, fund_wallet | | Coffee (Nowwa) | list_coffees, order_coffee | | Hotel (Club Med) | list_properties, list_rooms, book_room | | Office supplies | list_supplies, check_inventory, order_supplies, set_reorder_rule, list_supply_orders | | Receipts | list_transactions |

Each tool is a thin HTTPS wrapper — no LLM involvement inside the MCP server. Your local agent decides what to call.

Install

npm install -g @curless/mcp-server

Or run on-demand via npx:

npx @curless/mcp-server

Configure your client

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "curless": {
      "command": "npx",
      "args": ["-y", "@curless/mcp-server"]
    }
  }
}

Restart Claude Desktop. The 18 tools appear under the 🔌 menu.

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "curless": {
      "command": "npx",
      "args": ["-y", "@curless/mcp-server"]
    }
  }
}

Cline (VS Code extension)

Open the Cline panel → Settings → MCP Servers → paste the same JSON.

Custom (Python / LangChain / etc.)

Spawn the binary with stdio transport. See the MCP client examples for your framework.

Try it

Once connected, ask your agent:

• "Create a VCC with a $50 limit" → mints a card
• "Top up the card with $20" → moves USDC wallet → card
• "Order a Coconut Latte" → charges, returns order_id
• "Book Club Med Bali for June 1-4" → real booking flow
• "A4 paper is running low, order 5 reams" → procurement flow
• "What's my wallet balance?" → quick check

The agent will discover the right tool from the description. Names work in Chinese too: "订一杯椰漾拿铁", "帮我订巴厘岛 Club Med, 9月1日入住, 9月4日退房", etc.

Configuration

All optional, set as environment variables:

| Variable | Default | Purpose | |---|---|---| | CURLESS_BASE_URL | https://openclaw.curless.ai | Backend host. Point to staging or a self-hosted Curless. | | CURLESS_WALLET_ID | wal-002 | Which demo wallet to use. (wal-001 TravelBot · wal-002 ProcureAI · wal-003 BookingBot · wal-004 SupplyAgent) | | CURLESS_AGENT_ID | agent-002 | Default agent identity stamped on minted VCCs. | | CURLESS_STAMP_PREFIX | mcp | Prefix on agent_id so MCP-originated records (e.g. mcp-agent-002) are distinguishable from web-UI traffic in the merchant dashboard. | | CURLESS_AUTO_OPEN_URLS | unset | If true or 1, terminal actions (order_coffee / book_room / order_supplies) auto-launch the storefront confirmation page in the user's default browser. Off by default — the URL is still surfaced as a clickable link in the tool response. |

Storefront page after order

The web UI animates an embedded iframe through catalog → cart → order detail after a successful purchase. Desktop MCP clients (Claude Desktop, Cursor, Cline) don't have an iframe context, so each terminal tool now returns a view_url plus a markdown 🔗 Open in browser: content block that clients render as a clickable link. Click → real browser opens to the order page on nowwa / clubmed / procurement.

For agents that should open the page without user interaction (kiosk demos, hands-free walkthroughs), set CURLESS_AUTO_OPEN_URLS=true. The MCP server then spawns the OS browser via open / xdg-open / start the moment a successful order returns.

Example in claude_desktop_config.json:

{
  "mcpServers": {
    "curless": {
      "command": "npx",
      "args": ["-y", "@curless/mcp-server"],
      "env": {
        "CURLESS_WALLET_ID": "wal-004",
        "CURLESS_STAMP_PREFIX": "my-bot",
        "CURLESS_AUTO_OPEN_URLS": "true"
      }
    }
  }
}

Tool semantics

State maintained by the server

The server keeps one piece of state in memory across tool calls: the most recently created VCC id. So a typical session looks like:

> Create a VCC for $100
  → vcc-abc123 (server remembers this)
> Top up the card with $30
  → no vcc_id needed; uses vcc-abc123
> Order a Cold Brew
  → no vcc_id needed; uses vcc-abc123

If you have multiple VCCs in flight, pass vcc_id explicitly.

Per-tool agent stamping

To keep merchant analytics sane, orders are tagged with the appropriate agent based on tool category:

| Tool category | agent_id stamped on records | |---|---| | Coffee (order_coffee) | ${CURLESS_STAMP_PREFIX}-agent-002 | | Hotel (book_room) | ${CURLESS_STAMP_PREFIX}-agent-001 | | Supplies (order_supplies, set_reorder_rule, …) | ${CURLESS_STAMP_PREFIX}-agent-004 | | VCC mint | ${CURLESS_STAMP_PREFIX}-${CURLESS_AGENT_ID} |

With the default STAMP_PREFIX=mcp, your MCP-driven traffic is searchable as mcp-agent-* in the Curless merchant dashboard.

Scheduled orders

order_supplies accepts scheduled_for: "2026-07-21". Scheduled orders are queued, not charged immediately, and don't require a VCC.

Error envelope

Every tool returns either a success object or an error envelope:

{ "error": "insufficient_funds", "code": "VCC_INSUFFICIENT", "hint": "Top up via top_up_vcc and retry." }

isError: true is set on the MCP response so your client can short-circuit on failure.

Limitations of v0.1

• Shared wallets. All installs share wal-001..wal-004. Your agent can see other users' orders. Do not use real money.
• No real money flow. USDC transfers are simulated server-side. Card charges go through merchantChargeService but no card rail is involved.
• No retries / circuit breaker. The client makes one attempt per call and surfaces the error.
• No webhook callbacks. Long-running scheduled orders complete silently — no push notifications.

v0.2 will address these via API keys, real on-chain settlement, and webhook delivery.

Development

git clone https://github.com/onelabs-spark/curless-agent-payment.git
cd curless-agent-payment/mcp-server
npm install
npm run dev   # uses tsx — restart on save

To test against a local backend:

CURLESS_BASE_URL=http://localhost:3000 npm run dev

To smoke-test individual tools without a chat client, use any MCP inspector (e.g. npx @modelcontextprotocol/inspector npx @curless/mcp-server).

License

MIT