Buy with an agent, no code

Give your coding agent the power to shop and pay in Brazil — MCP-first, no code. Search a real store, hold a governed wallet, pay under a signed mandate.

@codespar/mcpv0.5.8

Your agent is the shopper: it searches real stores, assembles a purchase, and pays with money it holds under a signed mandate. This quickstart is MCP-first — you add one MCP server to the coding agent you already use and drive the whole loop in natural language. No SDK required.

Building the other side (an agent that sells and collects)? That's the seller quickstart — SDK-first: checkout, charge, invoice.

Prerequisites

A CodeSpar API key — mint one at Dashboard → API Keys. New accounts get a test-environment project plus a csk_test_* key auto-created at signup.
A coding agent that speaks MCP (Claude Code, Codex CLI, Cursor, VS Code, or any MCP client).

Add the CodeSpar MCP server

claude mcp add codespar --env CODESPAR_API_KEY=csk_test_your_key -- npx -y @codespar/mcp@0.5.8 serve

codex mcp add codespar --env CODESPAR_API_KEY=csk_test_your_key -- npx -y @codespar/mcp@0.5.8 serve

claude mcp add --transport http codespar https://connect.codespar.dev/mcp \
  --header "Authorization: Bearer csk_test_your_key"

The hosted endpoint speaks MCP Streamable HTTP — same 14 meta-tools, same mandate governance and audit as the stdio server.

One-click install buttons in the clients section of codespar.dev/mcp: Cursor and VS Code open with the hosted endpoint and the Authorization header filled in; replace csk_test_your_key_here with your key. The same section has the mcp.json block to paste by hand.

On a missing or invalid key, the server boots into a guided setup mode instead of crashing — ask your agent to run codespar_get_started and it walks itself through minting a key and validating the connection.

Shop a real store

Talk to your agent in plain language — under the hood it drives codespar_shop: live search, then the store's real checkout session, polled until the payable Pix is ready.

agent · buyer agent
sb_buyer_q1

Search Cobasi for ração golden retriever 15kg and buy the best-priced one.

Achei 6 opções. A melhor: Ração Premier Golden 15kg, R$ 179,90. Iniciando o checkout da loja...

Checkout pronto. Total R$ 179,90 com frete. Pix copia-e-cola gerado pela loja — posso pagar com a carteira?

S
codespar_shop  →  search✓ done1.2s

C
codespar_shop  →  checkout✓ done84s

C
codespar_shop  →  checkout_status✓ done420ms

3 tool calls · checkout session polled to ready_for_paymentRun this cookbook in Sandbox →

Check the wallet your agent spends from

Ask "what's my wallet balance?" — that's codespar_wallet action=balance: the governed funds plus the Pix key bound to them. To top up in the sandbox, action=receive mints a Pix copia-e-cola a payer can pay.

Pay under a mandate

"Pay this checkout with my wallet" calls codespar_pay with the checkout's Pix code. The spend only executes inside a signed mandate: per-currency caps, per-transaction caps, merchant allowlists, and expiry are enforced server-side — an out-of-policy payment is blocked, not trusted to the model. Every step lands in the audit ledger and the settlement produces a signed receipt.

Sandbox status

Search and checkout run against real store catalogs today; paying a real store's Pix code with real money requires production rails on your account. In the test environment the full loop executes against sandbox rails.

Start from a starter kit

A csk_test_ key opens the starter kits: an agent that pays under a signed mandate, with approval and a receipt, in the sandbox by construction. Clone, add the key, run:

git clone https://github.com/codespar/agent-starter-kits && cd agent-starter-kits
cp agents/bills-agent/.env.example agents/bills-agent/.env   # CODESPAR_API_KEY=csk_test_...
npm install && npm run consent -- --yes && npm start

Measured 77 s from clone to first receipt, in staging, on 2026-09-23. A csk_live_ key changes the key, the approved consumer_id and the webhook endpoint; the code, the agent.yaml and the approval key do not change.