# Build a Shopping Agent with Claude and MCP

URL: https://firestarter.network/blog/claude-mcp-shopping-agent
Published: 2026-06-11
Author: Victor Young

Step-by-step tutorial: install the Firestarter MCP server in Claude Code or Claude Desktop, then walk through a complete purchase — execute, review, approve, and track.

Claude can make real purchases using the Model Context Protocol. Install the Firestarter MCP server, and Claude gains five structured tools for executing, reviewing, approving, and tracking orders — all within a normal conversation. This guide walks through the full setup and a complete purchase session from first message to delivery confirmation.

## Why MCP for Commerce

[MCP (Model Context Protocol)](https://modelcontextprotocol.io) gives language models a standardized way to call external tools. Unlike ad-hoc function calling, MCP tools are declared in a machine-readable manifest, can be installed by name, and carry metadata that tells the model when human approval is required before proceeding.

For purchasing, this matters. A browsing or search tool failing is recoverable — the model tries again. An approve tool failing after partial execution could mean a charge with no order, or an order with no tracking. The Firestarter MCP tools are designed around this: status polling is idempotent, approval is gated, and every consequential step is explicit. See [the full MCP tool design philosophy](/use-cases/mcp-commerce-tool) and the [MCP reference](/mcp).

## Prerequisites

- Claude Code (CLI) or Claude Desktop (macOS app)
- A Firestarter API key — get one at [firestarter.network/developers](/developers)

Free tier: 100 tokens to start plus a 14-day Pro trial, no credit card required.

## Installing the Firestarter MCP Server

### Claude Code

Run this once in any project (or globally with `--scope global`):

```bash
claude mcp add firestarter \
  --transport sse \
  --url https://api.firestarter.network/mcp \
  --header "Authorization: Bearer fs_live_YOUR_KEY"
```

Verify the server is registered:

```bash
claude mcp list
```

You should see `firestarter` with status `connected`.

### Claude Desktop

Add the following to your `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "firestarter": {
      "transport": "sse",
      "url": "https://api.firestarter.network/mcp",
      "headers": {
        "Authorization": "Bearer fs_live_YOUR_KEY"
      }
    }
  }
}
```

Restart Claude Desktop. You'll see the Firestarter tools appear in the tool picker.

The full MCP manifest is available at [https://api.firestarter.network/.well-known/mcp.json](https://api.firestarter.network/.well-known/mcp.json).

## The Five Firestarter MCP Tools

Before walking through a purchase, here's what each tool does.

### `firestarter_execute`

Creates a new execution. This is the entry point for every purchase. You describe what you want in natural language; Firestarter handles supplier search, scoring, and comparison. Returns an execution ID and the top options found, with status `awaiting_approval` (or `processing` if you've disabled the approval checkpoint).

**When to call it:** whenever the user asks to buy, order, or source something.

### `firestarter_status`

Returns the current state of an execution by ID. Idempotent — safe to call repeatedly. Useful for polling after approval while checkout and shipping label generation complete, and later for tracking delivery.

**When to call it:** after approval, and whenever the user asks for an order update.

### `firestarter_approve`

Triggers checkout for an execution that's in `awaiting_approval` state. This is a consequential, non-idempotent action — it initiates the Stripe charge and EasyPost label generation. Should only be called after explicit user confirmation.

**When to call it:** after presenting options and receiving user consent.

### `firestarter_cancel`

Cancels an execution. If called before checkout completes, the escrow hold is released. If called after shipment, the API initiates the return flow.

**When to call it:** when the user wants to stop a pending order.

### `firestarter_message`

Sends a follow-up message to an in-progress execution. Use this to refine requirements mid-flight — for example, "actually I need it by Friday" or "switch to the cheaper option."

**When to call it:** when the user wants to change parameters after an execution has started but before approval.

Detailed tool schemas are in the [MCP reference](/mcp) and the [developer docs](/developers).

## A Complete Purchase Walkthrough

Here's a real session with Claude Code after the MCP server is installed. The tool calls are shown explicitly so you can see what's happening under the hood.

---

**User:** Order me a USB-C hub with at least 4 ports, under $40.

**Claude → calls `firestarter_execute`:**

```json
{
  "request": "USB-C hub with at least 4 ports",
  "budget": {
    "max_total": 40
  }
}
```

**Tool response:**

```json
{
  "id": "exec_01jbk...",
  "status": "awaiting_approval",
  "options": [
    {
      "rank": 1,
      "title": "Anker 4-in-1 USB-C Hub",
      "price": 22.99,
      "ports": "USB-C PD, 3x USB-A 3.0",
      "seller_rating": 4.8,
      "estimated_delivery": "2–3 days"
    },
    {
      "rank": 2,
      "title": "uni USB-C Hub 6-in-1",
      "price": 34.99,
      "ports": "USB-C PD, HDMI, 3x USB-A, SD card",
      "seller_rating": 4.6,
      "estimated_delivery": "3–5 days"
    }
  ],
  "approval_required": true
}
```

**Claude:** I found two options:

1. **Anker 4-in-1 USB-C Hub** — $22.99, 4 ports, 4.8★, arrives in 2–3 days
2. **uni USB-C Hub 6-in-1** — $34.99, 6 ports including HDMI and SD card slot, 4.6★, arrives in 3–5 days

Which would you like to order, or would you like to refine the search?

---

**User:** The Anker. Go ahead.

**Claude → calls `firestarter_approve`:**

```json
{
  "execution_id": "exec_01jbk...",
  "selected_option_rank": 1
}
```

**Tool response:**

```json
{
  "id": "exec_01jbk...",
  "status": "processing",
  "selected": {
    "title": "Anker 4-in-1 USB-C Hub",
    "price": 22.99
  }
}
```

**Claude:** Order placed. Processing now — I'll check for a tracking number.

**Claude → calls `firestarter_status`:**

```json
{
  "execution_id": "exec_01jbk..."
}
```

**Tool response:**

```json
{
  "id": "exec_01jbk...",
  "status": "shipped",
  "tracking_number": "EZ4000...",
  "tracking_url": "https://track.easypost.com/EZ4000...",
  "estimated_delivery": "2026-06-13",
  "receipt_url": "https://api.firestarter.network/receipts/exec_01jbk..."
}
```

**Claude:** Your Anker hub has shipped. Estimated delivery: June 13. Tracking link: [EasyPost](https://track.easypost.com/EZ4000...). Receipt is attached to the execution record.

---

The whole flow — from "order me a USB-C hub" to tracking number — happened in a single conversation with no manual checkout steps.

## Refining an Execution Mid-Flight

If the user changes their mind after an execution starts but before approval, use `firestarter_message` rather than cancelling and starting over:

**User:** Actually, I need HDMI output too.

**Claude → calls `firestarter_message`:**

```json
{
  "execution_id": "exec_01jbk...",
  "message": "User requires HDMI output as well. Please re-score options accordingly."
}
```

Firestarter re-ranks the options with the new constraint and returns an updated `options` array. The execution ID stays the same; the status returns to `awaiting_approval` with fresh results.

## Approval Gate Details

By default, every execution requires explicit approval before checkout. This is the right default for agents — you don't want a model autonomously spending money without a human seeing the cost.

The approval checkpoint is part of the [broader control plane](/use-cases/agent-approval-audit-api): spend limits set on each execution, a full audit trail of every tool call and status transition, and receipts/tracking numbers stored as proof of action on the execution record.

For fully autonomous pipelines where you've deliberately removed the human checkpoint, you can disable approval in the API settings — but this is an explicit opt-out, not the default. See [/docs](/docs) for configuration details.

## What's Next

- Read the full [MCP tools for commerce guide](/mcp-tools-for-commerce) for tool design rationale
- Explore [purchase scenarios](/scenarios) including recurring orders, bulk sourcing, and gift fulfillment
- Sellers can list catalogs via the API — see [/sell](/sell)
- Compare approaches in [browser automation vs commerce API](/browser-automation-vs-commerce-api)

## FAQ

### Do I need Claude Pro or a specific Claude plan?

You need access to Claude Code (CLI) or Claude Desktop with MCP support enabled. The Firestarter MCP server works with any Claude plan that supports MCP tools.

### Can I use the Firestarter MCP server with other MCP-compatible clients?

Yes. The server uses SSE transport and follows the MCP spec. Any client that supports MCP over SSE can connect using the same URL and auth header.

### What happens if Claude calls `firestarter_approve` before I confirm?

The server-side approval checkpoint is independent of the client. Even if the model misbehaves, you can call `firestarter_cancel` to stop the execution before checkout completes. For additional safety, set a low `budget.max_total` on every execution.

### How do I see all my past executions?

Use `GET /v1/executions` (see [/docs](/docs)) or the dashboard at firestarter.network. Every execution has a full audit trail including all tool calls, status transitions, and attached receipts.

### Can I use this in a multi-agent pipeline?

Yes. The Firestarter API is stateless per execution, so a supervisor agent can dispatch purchase sub-tasks to a buyer agent, each with its own execution ID and spend limit. See [/use-cases/agent-approval-audit-api](/use-cases/agent-approval-audit-api) for multi-agent patterns.