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.

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.

Install

Claude Code

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

{
  "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

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.

Create a Store Connection Token

Create connection tokens from the hosted Store account page before you install the MCP server:

Open Store account

Create a connection

In Connect your agent, choose the client (Claude Code, Claude Desktop, Codex, OpenClaw, Other MCP, or Raw API), give the connection a recognizable name, and create the token.

Copy the install snippet immediately

Conto only shows the raw conto_store_... token once. Copy the generated MCP or REST snippet before you leave the page.

Complete AgentScore verification if prompted

Some Store connection flows open an AgentScore verification card after token creation. Finish the verification in the browser, then return to the Store account page and use Check verification to save the verified state on the connection.

Default Store connection tokens are scoped for merchant browsing and checkout:

Scope	Used by
`menu:read`	`list_merchants`, `get_menu`
`cart:write`	`build_cart`
`quote:create`	`create_quote`
`checkout:start`	`start_checkout`
`orders:read`	`get_order_status`, `list_orders`

Approval links stay out of the agent channel. When a checkout needs owner approval, Conto emails the owner directly. If auto-pay is armed and the saved-ceiling charge succeeds, the MCP response returns mode: "paid" instead.

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

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

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

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:

{
  "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:

{
  "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.

Start

Products

Build

Guides

Reference

Changelog

General Store MCP

General Store MCP

Install

Claude Code

Claude Desktop and other MCP clients

Raw REST

Environment

Create a Store Connection Token

Tools

REST examples

Build a cart

Create a quote

Start checkout

Errors

​General Store MCP

​Install

​Claude Code

​Claude Desktop and other MCP clients

​Raw REST

​Environment

​Create a Store Connection Token

​Tools

​REST examples

​Build a cart

​Create a quote

​Start checkout

​Errors

General Store MCP

Install

Claude Code

Claude Desktop and other MCP clients

Raw REST

Environment

Create a Store Connection Token

Tools

REST examples

Build a cart

Create a quote

Start checkout

Errors