> ## Documentation Index
> Fetch the complete documentation index at: https://conto.finance/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# General Store MCP

> Connect Claude Code, Claude Desktop, Codex, OpenClaw, or another MCP client to the Conto General Store

# General Store MCP

Use `@conto_finance/general-store-mcp` when your own agent should browse the
General Store, build carts, create quotes, request owner-approved checkout, and
track order status.

<Info>
  The Store MCP server uses a Store connection token (`conto_store_...`), not an agent SDK key.
  Approval and payment links are never returned through the agent channel; the account owner
  receives those out of band.
</Info>

## Install

### Claude Code

```bash theme={null}
claude mcp add general-store \
  --env CONTO_STORE_TOKEN=conto_store_xxx... \
  --env CONTO_STORE_BASE_URL=https://conto.finance/api/store/v1 \
  -- npx -y @conto_finance/general-store-mcp
```

### Claude Desktop and other MCP clients

```json theme={null}
{
  "mcpServers": {
    "general-store": {
      "command": "npx",
      "args": ["-y", "@conto_finance/general-store-mcp"],
      "env": {
        "CONTO_STORE_TOKEN": "conto_store_xxx...",
        "CONTO_STORE_BASE_URL": "https://conto.finance/api/store/v1"
      }
    }
  }
}
```

### Raw REST

```bash theme={null}
curl https://conto.finance/api/store/v1/merchants \
  -H "Authorization: Bearer conto_store_xxx..."
```

Base URL: `https://conto.finance/api/store/v1`

Required header: `Authorization: Bearer $CONTO_STORE_TOKEN`

## Environment

| Variable               | Default                              | Required                                               |
| ---------------------- | ------------------------------------ | ------------------------------------------------------ |
| `CONTO_STORE_TOKEN`    | none                                 | Yes. Store connection token, format `conto_store_...`. |
| `CONTO_STORE_BASE_URL` | `https://conto.finance/api/store/v1` | No. Override for local dev.                            |

## Tools

| Tool                                         | REST endpoint                | Purpose                                                                                                  |
| -------------------------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------- |
| `list_merchants()`                           | `GET /merchants`             | List live merchants with open-now and prep-time data.                                                    |
| `get_menu({ merchant })`                     | `GET /merchants/{slug}/menu` | Read available menu items.                                                                               |
| `build_cart({ merchant, items })`            | `POST /carts`                | Build or replace the connection cart.                                                                    |
| `create_quote({ cartId })`                   | `POST /quotes`               | Price the cart and show limits, expiry, and `autoPayArmed`.                                              |
| `start_checkout({ quoteId })`                | `POST /checkout`             | Request checkout. Unarmed BYO orders return `approval_pending`; auto-pay armed orders can return `paid`. |
| `get_order_status({ orderId or orderCode })` | `GET /orders/{id}`           | Read status, approval sub-state, and timeline.                                                           |
| `list_orders({ status? })`                   | `GET /orders`                | List recent orders, optionally filtered by status.                                                       |
| `get_limits()`                               | `GET /limits`                | Read per-order cap, daily cap, and remaining daily budget when the token has `profile:read`.             |

## REST examples

### Build a cart

```bash theme={null}
curl -X POST https://conto.finance/api/store/v1/carts \
  -H "Authorization: Bearer $CONTO_STORE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "merchant_123",
    "items": [{ "menuItemId": "item_123", "qty": 1 }]
  }'
```

### Create a quote

```bash theme={null}
curl -X POST https://conto.finance/api/store/v1/quotes \
  -H "Authorization: Bearer $CONTO_STORE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "cartId": "cart_123" }'
```

### Start checkout

```bash theme={null}
curl -X POST https://conto.finance/api/store/v1/checkout \
  -H "Authorization: Bearer $CONTO_STORE_TOKEN" \
  -H "Idempotency-Key: general-store-mcp:quote_123" \
  -H "Content-Type: application/json" \
  -d '{ "quoteId": "quote_123" }'
```

For the default approval lane, the response is an order state for the agent and
an approval email for the owner:

```json theme={null}
{
  "mode": "approval_pending",
  "orderId": "order_123",
  "orderCode": "GS-123ABC"
}
```

For an auto-pay armed quote, Conto can complete the charge under the owner’s
saved ceiling and return a paid state without returning a payment link:

```json theme={null}
{
  "mode": "paid",
  "orderId": "order_123",
  "orderCode": "GS-123ABC",
  "paymentIntentId": "pi_123",
  "message": "Store auto-pay completed with the saved payment method."
}
```

## Errors

The MCP package maps Store API errors into agent-readable messages:

| API outcome             | Agent guidance                                                                    |
| ----------------------- | --------------------------------------------------------------------------------- |
| `429` or `rate_limited` | Back off before retrying.                                                         |
| `policy_denied`         | Tell the operator which cap or policy blocked checkout from the response details. |
| `agent_blocked`         | Ask the operator to check AgentScore verification or reputation.                  |
| `insufficient_scope`    | Ask the owner to edit connection scopes.                                          |
| `validation_failed`     | Fix the tool input and retry.                                                     |

The package sends `user-agent: general-store-mcp/<version>` on every request and
does not log `CONTO_STORE_TOKEN`.