Seller API — MCP & CLI
Manage your Provision store from your own agent or scripts. The API is a Model Context Protocol server: any MCP-capable client (Claude Code, Claude.ai connectors, your own stack) connects and discovers every tool automatically via tools/list — the schemas below are served live from the same definition our Seller Copilot runs on. Same gates, different door: everything is scoped to your store, buyer data is never exposed, and submissions land in the same human review queue as every other path.
Get a key
Keys are self-serve for active sellers — no application, no wait. Create a seller account, complete your business profile, then generate a key at Seller portal → API keys. The full key is shown exactly once; revoke it there any time. Keys stop working immediately if your seller account is suspended.
Connect
Endpoint (Streamable HTTP, stateless — one JSON-RPC message per POST):
POST https://seller.infinityfall.com/api/mcp
Authorization: Bearer pk_live_…
Content-Type: application/json
{"jsonrpc":"2.0","id":1,"method":"tools/list"}In Claude Code: claude mcp add provision --transport http https://seller.infinityfall.com/api/mcp--header "Authorization: Bearer pk_live_…"
CLI
A thin CLI ships in the Provision repo and wraps the same endpoint — useful for scripts and cron:
export PROVISION_API_KEY=pk_live_… npm run cli -- overview # store, submissions, reliability, placement npm run cli -- queue # ship-today queue npm run cli -- ship ord_… # mark shipped (buyer is notified) npm run cli -- demand # what buyers are asking for npm run cli -- submit listing.json # file a submission (same quality gate)
Tool reference
Rendered from the live agent definition — identical to what tools/list returns.
get_store_overview
The seller's whole store at a glance: live products and pending/rejected submissions (with quality scores and reviewer notes), reliability (on-time ship rate), and placement analytics — per-product surfaced/carted/bought counts, quality vs category average, and honest improvement suggestions derived from their metadata. Call this before answering questions about how the store is doing or why the shopping agent does/doesn't recommend something.
get_ship_queue
Open orders (placed/confirmed) containing this seller's items, sorted by promised ship-by date, with risk flags (late / ship today / due tomorrow). This is the seller's working queue for the day. Orders whose items all belong to this seller carry next_action confirm or ship; mixed-seller orders are visible but coordinated by Provision.
advance_order
Confirm an order or mark it shipped. STRICT PRECONDITION: call only after restating the order id, its items, and the action to the seller and getting an explicit yes. Only legal transitions succeed (placed→confirmed→shipped), only on orders whose items ALL belong to this seller. The buyer is notified automatically and on-time metrics derive from these timestamps.
| Field | Type | Description |
|---|---|---|
| order_id* | string | The order to advance. |
| to* | confirmed | shipped | Target status: "confirmed" (accept) or "shipped". |
| seller_confirmed* | boolean | True ONLY if the seller answered yes to your restated order + action. |
list_orders
Order history: every order that includes this seller's items, any status, newest first — including packing-slip availability. Use for questions about past orders; use get_ship_queue for what needs action today.
get_demand_signals
"What should I make next": real aggregate demand from buyer conversations in this seller's categories over the recent window — searches the catalog answered weakly (with result counts) and outside products buyers asked about (with request counts and Provision-fit assessments). Aggregates only; buyers are never identified. Frame results as product-line opportunities, not orders.
draft_listing
Draft an honest product listing from the seller's own rough notes (their words, not yours — pass them through faithfully). Returns drafted quality-metadata fields plus open questions for facts the notes did not establish. The draft is a PROPOSAL: present it to the seller field by field, get their corrections, and never submit until they explicitly confirm every claim is theirs and true. Drafted submissions carry provenance (original notes + open questions) into human admin review.
| Field | Type | Description |
|---|---|---|
| notes* | string | The seller's own description of the product — at least a few sentences, verbatim where possible. |
| category_hint | kitchen | home_goods | outdoor | electronics_accessories | Category if the seller named one; omit to let the drafter propose. |
submit_product
File a product submission into the human admin review queue. STRICT PRECONDITION: the seller has reviewed every field value and explicitly confirmed the facts are theirs and true — set seller_confirmed=true only then. The submission is validated against the same quality gate as the web form; on field errors, relay them honestly and fix WITH the seller (never by inventing content). Prices are in cents. attributes must match the category's declared fields (get an error? the message names what's missing).
| Field | Type | Description |
|---|---|---|
| seller_confirmed* | boolean | True ONLY if the seller explicitly confirmed every field of this exact submission. |
| draft_used | boolean | True when draft_listing produced any part of this submission (provenance is attached). |
| original_notes | string | The seller's original rough notes when draft_used is true — stored as provenance for review. |
| name* | string | |
| category* | kitchen | home_goods | outdoor | electronics_accessories | |
| price_cents* | integer | |
| price_benchmark_cents | integer | Comparable market price in cents, if the seller cites one. |
| price_benchmark_note | string | What the benchmark refers to (product + source). |
| ship_commitment_days* | integer | |
| materials* | string | |
| construction* | string | |
| durability_notes* | string | |
| value_rationale* | string | |
| sourcing_story* | string | |
| care_instructions | string | |
| attributes* | object | Per-category attribute object (e.g. kitchen: blade_material, handle_material, dimensions, ...). |
Rate limits are generous for real stores; abuse gets keys revoked. Questions or a use case the tools don't cover? Tell us — the surface grows with sellers' needs.