MCP server

STOQ API v2: preorders and back-in-stock, 226 actions reached through search / execute_read / execute_write instead of one tool per action, plus docs tools that need no sign-in at https://app.stoqapp.com/api/v2/external/mcp/docs (docs only). Connector URL: https://app.stoqapp.com/api/v2/external/mcp. Sign in with OAuth from an MCP client, or send the X-Auth-Token API key. Full guide: GET /api/v2/external/preorders/skill.md

Server stoq-api-v2, version 2.0.0. To connect it to an AI app, see MCP setup.

search

Search the Stoq API v2 action catalog by keyword — matches path, description, aliases, and notes (e.g. “deposit”, “widget button color”, “cancel order”, “back in stock signup”). Returns method + path + description for each match. A search that narrows to 3 or fewer actions also includes the full request JSON Schema for each, so you know exactly what params execute_read/execute_write expect. Call with an empty query to browse the full catalog.

Read-only.

Parameter	Type	Description
query	string	Keyword(s) to search for. Empty string browses everything.
method (optional)	string	Optional: restrict results to one HTTP method. One of: GET, POST, PATCH, DELETE.
limit (optional)	integer	Max results to return. Default 20.

execute_read

Call a read (GET) action from the Stoq API v2 catalog. Use search first to find the right method + path and see what params it expects. path must be concrete — substitute real ids for any :placeholder segment. An unregistered path, or one registered under a different method, returns a structured error rather than raising. Responses carry every field the action returns by default. Pass response_format: “concise” when you only need an overview or are reading many rows: list actions then return 20 rows a page unless you send per_page, null and blank fields are left out, readable fields (name, title, status) come first and ids are kept for follow-up calls, and lists inside a row show their first 25 items. A response is capped at about 6000 tokens (concise) or 25000 tokens (detailed); anything cut is listed under truncated, and next_page is the exact execute_read call for the next rows.

Read-only.

Parameter	Type	Description
method	string	HTTP method — must be GET. One of: GET.
path	string	Concrete action path from search, e.g. “/preorders/offers/123/widget” (real ids in place of any :placeholder).
params (optional)	object	Request body for this action (see the request_schema from search).
response_format (optional)	string	detailed (default): every field the action returns. concise: fewer rows, readable fields first, ids kept, nulls left out. One of: concise, detailed.

execute_write

Call a write (POST/PATCH/DELETE) action from the Stoq API v2 catalog. Use search first to find the right method + path and see what params it expects. path must be concrete — substitute real ids for any :placeholder segment. An unregistered path, or one registered under a different method, returns a structured error rather than raising. Send a fresh idempotency_key (e.g. a new UUID) with every write, and the same key only when retrying that write: the same key with the same arguments within 1 hour returns the first result without running again.

Writes data, can be destructive.

Parameter	Type	Description
method	string	HTTP method — must be POST or PATCH or DELETE. One of: POST, PATCH, DELETE.
path	string	Concrete action path from search, e.g. “/preorders/offers/123/widget” (real ids in place of any :placeholder).
params (optional)	object	Request body for this action (see the request_schema from search).
idempotency_key (optional)	string	A fresh unique key (e.g. a new UUID) for every write; reuse it only to retry that write. Retrying with the same key and the same arguments within 1 hour returns the first result (idempotent_replay: true) instead of writing twice; the same key with different arguments is refused (idempotency_key_reused).

generate_storefront_widget

Generate a ready-to-paste STOQ storefront widget snippet for a variant — a preorder widget/button, a notify-me (back-in-stock) form, or event-tracking listeners. Two surfaces: surface=sdk for headless/Hydrogen (@artossoftware/stoq-sdk), surface=theme for a Shopify theme running the STOQ app embed (window._RestockRocket + Liquid). Aliases: generate widget, scaffold preorder button, create notify-me snippet, give me the embed code, theme javascript snippet, headless preorder code, hydrogen example. Returns code, not an API call.

Read-only.

Parameter	Type	Description
surface (optional)	string	sdk = headless/Hydrogen via @artossoftware/stoq-sdk. theme = Shopify theme with the STOQ app embed (window._RestockRocket API + Liquid). Default sdk. One of: sdk, theme.
widget	string	Which snippet to generate. events = analytics listeners for the stoq:* events. One of: preorder, notify_me, product_page, events.
format (optional)	string	For surface=sdk only. Output flavor; default custom-element. Ignored for surface=theme. One of: custom-element, script-tag, react.
variant_id (optional)	string	Shopify variant id to embed (optional).
product_id (optional)	string	Shopify product id — required for notify-me.

search_help_docs

Search STOQ’s docs, or read one page in full: the help centre and the developer docs. Use this for how-to and explanation questions — how a feature works, how to set something up, what a setting means — instead of guessing. Search first, then read the page that matches before giving step-by-step instructions; the snippets are previews, not the whole answer. Each result has source (help, developer, api or contract).

Read-only.

Parameter	Type	Description
audience	string	Which docs answer the question. Pick by what the question is about, not who is asking. “merchant”: using the STOQ app (setting up preorders, back-in-stock alerts, the Notify me button, emails, settings, billing). “developer”: building on STOQ (the API, webhooks, the SDK, metafields, storefront code, MCP). “all”: the question spans both, or you can’t tell. Defaults to merchant. Ignored when reading a url. One of: merchant, developer, all.
query (optional)	string	What to search for. Phrase it like an article title or a feature name (“split fulfillment”, “notify me button”) rather than the merchant’s exact words.
url (optional)	string	A help.stoqapp.com or docs.stoqapp.com URL returned by a previous search. Supply this to read that page in full instead of searching.
limit (optional)	integer	How many search results to return. Defaults to 10, which is also the maximum.
offset (optional)	integer	When reading a url whose result had next_offset, pass it here to read on.

learn_stoq

Call this first. A primer on STOQ (Restock Rocket, preorders and back-in-stock alerts for Shopify) for agents: what it is, how to connect a store (OAuth connector or API key), how the tools fit together, the conventions agents trip on, and the top tasks with their doc ids and API actions. Pick a topic to go deeper. Needs no sign-in.

Read-only.

Parameter	Type	Description
topic (optional)	string	Default overview. One of: overview, preorders, back_in_stock, storefront, data_contract, auth.

find_doc

Search STOQ’s public docs: the merchant help centre (help.stoqapp.com), the developer guides (docs.stoqapp.com: API v1/v2, SDK, MCP), one reference page per API action, and the storefront metafield data contract. Returns doc ids, titles, snippets, URLs and the API actions each page documents; snippets are previews, so read_doc the best match before relaying steps. Needs no sign-in.

Read-only.

Parameter	Type	Description
query	string	What to look for, in plain words (at most 200 characters).
audience	string	Which docs answer the question. Pick by what the question is about, not who is asking. “merchant”: using the STOQ app (setting up preorders, back-in-stock alerts, the Notify me button, emails, settings, billing). “developer”: building on STOQ (the API, webhooks, the SDK, metafields, storefront code, MCP). “all”: the question spans both, or you can’t tell. Defaults to merchant. One of: merchant, developer, all.
limit (optional)	integer	Max results, 1-10. Default 5.

read_doc

Read the full Markdown of up to 5 public STOQ docs, by the doc_id find_doc returned (e.g. “help:/general/ai-connectors/”) or by their help.stoqapp.com / docs.stoqapp.com URL. Long pages come back in 6000-character parts: pass the returned next_offset as offset to read on. Needs no sign-in.

Read-only.

Parameter	Type	Description
doc_ids	array	Doc ids from find_doc or learn_stoq, or help.stoqapp.com / docs.stoqapp.com URLs.
offset (optional)	integer	Character offset to read from (a previous next_offset). Default 0.