---
title: Quickstart (Buyer agent)
description: 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.
---

import { Callout } from "fumadocs-ui/components/callout";
import { Steps, Step } from "fumadocs-ui/components/steps";
import { Tab, Tabs } from "fumadocs-ui/components/tabs";

<VersionBadge pkg="@codespar/mcp" />

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.

<Callout type="info">
Building the other side (an agent that **sells and collects**)? That's the [seller quickstart](/docs/quickstart) — SDK-first: checkout, charge, invoice.
</Callout>

## Prerequisites

- A CodeSpar API key — mint one at [Dashboard → API Keys](https://codespar.dev/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).

<Steps>

<Step>
### Add the CodeSpar MCP server

<Tabs items={["Claude Code", "Codex CLI", "Remote (no local process)", "Cursor / VS Code"]}>
<Tab value="Claude Code">
```bash
claude mcp add codespar --env CODESPAR_API_KEY=csk_test_your_key -- npx -y @codespar/mcp serve
```
</Tab>
<Tab value="Codex CLI">
```bash
codex mcp add codespar --env CODESPAR_API_KEY=csk_test_your_key -- npx -y @codespar/mcp serve
```
</Tab>
<Tab value="Remote (no local process)">
```bash
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.
</Tab>
<Tab value="Cursor / VS Code">
One-click install buttons at [codespar.dev/agents](https://codespar.dev/agents) — they pre-fill the server config; you paste your key.
</Tab>
</Tabs>

<Callout type="info">
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.
</Callout>
</Step>

<Step>
### Shop a real store

Talk to your agent in plain language — under the hood it drives [`codespar_shop`](/docs/concepts/meta-tools/shop): live search, then the store's real checkout session, polled until the payable Pix is ready.

<ChatPreview
  agentName="buyer agent"
  sessionId="sb_buyer_q1"
  messages={[
    { role: "user", content: "Search Cobasi for ração golden retriever 15kg and buy the best-priced one." },
    { role: "agent", content: "Achei 6 opções. A melhor: Ração Premier Golden 15kg, R$ 179,90. Iniciando o checkout da loja..." },
    { role: "agent", content: "Checkout pronto. Total R$ 179,90 com frete. Pix copia-e-cola gerado pela loja — posso pagar com a carteira?" },
  ]}
  toolCalls={[
    { name: "codespar_shop", server: "search", status: "done", duration: "1.2s" },
    { name: "codespar_shop", server: "checkout", status: "done", duration: "84s" },
    { name: "codespar_shop", server: "checkout_status", status: "done", duration: "420ms" },
  ]}
  footer="3 tool calls · checkout session polled to ready_for_payment"
  sandboxLink="/dashboard/sandbox"
/>
</Step>

<Step>
### Check the wallet your agent spends from

Ask "what's my wallet balance?" — that's [`codespar_wallet`](/docs/concepts/meta-tools/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.
</Step>

<Step>
### Pay under a mandate

"Pay this checkout with my wallet" calls [`codespar_pay`](/docs/concepts/meta-tools/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.

<Callout type="warn" title="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.
</Callout>
</Step>

</Steps>

## Where to go next

<NextStepsGrid items={[
  { label: "COOKBOOK", title: "Shopping Agent", description: "The full buy-side loop as a recipe: search, checkout session, poll, pay from the governed wallet.", href: "/docs/cookbooks/shopping-agent" },
  { label: "META-TOOL", title: "codespar_wallet", description: "Balance, statement, top-up — the wallet your agent spends from, with per-currency slots.", href: "/docs/concepts/meta-tools/wallet" },
  { label: "CONCEPT", title: "Mandates & directed pay", description: "How the signed mandate caps and routes every spend, server-side.", href: "/docs/concepts/directed-pay" },
  { label: "CONCEPT", title: "Shopper identity", description: "Vaulted checkout identity so stores get real buyer details without re-asking.", href: "/docs/concepts/shopper-identity" },
]} />