Quickstart (Buyer agent)

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.2

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 serve

codex mcp add codespar --env CODESPAR_API_KEY=csk_test_your_key -- npx -y @codespar/mcp 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 tools, same mandate governance and audit as the stdio server.

One-click install buttons at codespar.dev/agents — they pre-fill the server config; you paste your key.

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.