Store MCP HTTP API Quickstart

The HTTP API uses the same operation definitions and authorization checks as MCP.

Prerequisites

Sign in and create an API key in Connect AI with View only access to your chosen store. Store the key in the STORE_MCP_KEY environment variable using your secret manager; do not paste it into a prompt. Shell examples below use POSIX syntax.

Steps

Discover schemas with GET https://store-mcp.com/api/tools and an Authorization: Bearer header. The result is {tools:[...]}.
Call POST /api/tools/stores.list with Content-Type: application/json and {}.
Select a returned Store MCP store ID, check stores.get, then call listings.list for that store.
Inspect ok before consuming data and compare the listing with your provider dashboard. Retain activityId for support without copying credentials or buyer data.

Safe example

The example uses synthetic names. Select your own authorized store and verify every identifier before a write.

curl https://store-mcp.com/api/tools -H "Authorization: Bearer $STORE_MCP_KEY"
curl https://store-mcp.com/api/tools/stores.list -H "Authorization: Bearer $STORE_MCP_KEY" -H 'Content-Type: application/json' -d '{}'

You’re done when…

Discovery returns the exact public schemas. An executed operation returns {ok:true,data,activityId} or {ok:false,error:{code,message,retryable,outcomeUnknown},activityId}. Approval failures can include approvalUrl and approvalId inside error; retryAfterSeconds is optional. MCP exposes the operation result as structuredContent and marks failures with isError.

Limitations

Edge authentication, rate-limit, malformed-body and unknown-route responses may use a different error envelope and omit activityId. Check HTTP status and parse defensively. The documented HTTP path is not a raw provider proxy.

MCP OAuth and API keys

MCP clients discover OAuth authorization and request browser consent, using PKCE and supported CIMD or dynamic registration. Seller OAuth separately connects a provider account to Store MCP; provider credentials never become client credentials.

Bearer API keys carry their own permission and store scope. Revoke them in Connect AI. Never broaden a grant to diagnose missing catalog data. Store MCP’s /mcp URL is not proof that every client supports its authentication.

Errors and retry rules

FORBIDDEN means permission or scope must be checked; NOT_FOUND does not establish that a foreign resource is accessible. PLAN_REQUIRED and SUBSCRIPTION_REQUIRED require reviewing Billing. CAPABILITY_UNAVAILABLE means the connected store lacks the operation; upgrades cannot add unsupported provider features.

INVALID_INPUT needs a schema-correct request. INVALID_CURSOR needs a fresh first page with consistent filters. QUOTA_EXCEEDED or RATE_LIMITED requires waiting or resolving the allowance; respect Retry-After or retryAfterSeconds when provided. APPROVAL_REQUIRED needs exact owner browser approval.

IDEMPOTENCY_CONFLICT means the same key was reused with changed arguments. For any outcomeUnknown: true, stop automatic retries and inspect operations.get plus provider state. retryable: true does not override an unknown write outcome. Transient read failures may be retried with bounded backoff.

Pagination, filters and coverage

Pass the returned nextCursor unchanged to the same tool with the same filters and limit. Cursors are bound to workspace, tool and input filters and expire. Do not decode them or replace them with provider page numbers. The normal page limit is 1–50; inventory.get has its own schema limit.

Order timestamps require ISO 8601 with an offset. Use createdAfter and createdBefore; createdAfter cannot follow createdBefore. Unsupported status/payment/fulfillment filters fail explicitly. Listing filters are sku and status; support varies by provider.

Inspect itemsComplete, variantsComplete, mediaComplete, skusComplete and other completeness fields. Null means unknown, not zero. A page is not a complete dataset; disclose unread pages and never claim a complete sales reconciliation from partial results.

Idempotency and safe writes

Receipt-backed mutations require idempotencyKey in the JSON body: 8–128 characters using letters, digits, underscores or hyphens. stores.connect is the exception: it starts a browser connection intent and does not accept idempotencyKey. Use a unique key for a new receipt-backed intent and the identical key and arguments only for a replay. Receipts are retained at least 30 days.

Completed identical replays return the saved result without a new provider action. Changed arguments conflict. Pending or unknown outcomes must be inspected with operations.get; do not use a new key to escape uncertainty. A completed request may still represent an asynchronous provider job, so re-read the affected resource.

A synthetic stock intent might use demo_stock_001. First read the exact inventory row, then review quantity and expectedQuantity before sending inventory.set. If approval is required for a different action, keep the original arguments and key when supplying approvalId.