Connection details
Authentication
The server accepts two credentials on the same URL. Use a browser sign-in when a person is at the client, and an API key when the client runs as a service.Sign in from an interactive client
There are no API keys to generate or rotate. MCP clients that implement OAuth 2.1 discovery walk the authorization chain automatically:- On the first tool call, your client opens a browser tab pointed at the StoreRouter sign-in page.
- You sign in with the email that belongs to your Developer organization. If you belong to multiple organizations, you choose which one to act as.
- You consent to the requested scopes.
- The browser redirects back to your client, which exchanges the authorization code for an access token and a refresh token.
Server-side integrations
A backend service, scheduled job, or hosted agent can’t complete a browser sign-in. Send your Developer organization’s API key as a bearer token on every request instead:curl, reading the key from the environment:
search_products is charged as a product search and lookup_product as a product lookup; lookup_products is charged one product lookup per URL in the batch. See API pricing and billing.
A key acts on its own organization only. Merchant organization keys are refused with 403. The BigQuery subscriber tools that change or list subscribers need a signed-in owner or admin, so they return not_authorized when called with a key.
Prerequisites
Both conditions must be true before your first tool call.
- You have a StoreRouter account that belongs to a Developer organization. If you don’t have one, sign up at platform.storerouter.ai and choose Developer when you create your organization. See Create an account.
- You can sign in to the StoreRouter Platform with the email that belongs to that organization.
Available tools
The product tools use the same catalog access policy as the Platform Catalog API v1.search_products also shares its request and successful response with REST search. Search failures use MCP’s isError flag and a JSON text error; see Search errors. Other tools retain their existing response and error formats.
Product tools
lookup_product
Resolves a product page URL to a full product record, including title, description, prices, sizes, colors, images, and identifiers. Use this when a user pastes a specific product URL. Pass catalogs to narrow the lookup to specific catalog keys. If no active product matches, the tool returns a structured product_not_found value.
lookup_products
Resolves up to 12 product URLs in one call. Results keep the input order, and each URL returns either its own product or its own error, so one miss does not fail the rest of the batch.
search_products
Searches all active crawled catalogs your organization can access. Pass the REST search request body directly as MCP arguments, with no request wrapper. All fields are optional, subject to the same validation rules as REST:
domain_not_covered. Selectors only narrow your organization’s access; they cannot grant access to merchant catalogs.
Search response
The tool’sstructuredContent is the REST page itself, with requestId, items, nextCursor, and effectiveQuery. For example, an empty browse page is:
result.structuredContent.items in a raw JSON-RPC response. The text content block contains the same page JSON.
Items use the REST product card, including primaryImage and images as image objects. Each call and page gets a fresh requestId. effectiveQuery describes what ran; keep your original request instead of replaying this report as arguments.
Search pagination
Keep the original arguments and replace onlycursor with the returned nextCursor. Stop when it is null. Invalid or mismatched cursors return invalid_cursor; start a new traversal by omitting cursor. REST and MCP cursors can be shared only when the request and authorized catalog scope match. Authorization is checked on every call.
Search errors
Search validation and expected execution errors return an MCP tool result withisError: true, no structuredContent, and a text content block containing JSON with requestId, error, and message. Validation errors also include detail. Check isError before parsing a successful page. Authentication and protocol errors retain their transport-level handling; see Rate limits for shared throttling errors.
Color and stock in search results describe the product family. Call
lookup_product to confirm that a particular variant is available.
Taxonomy discovery tools
Use these tools to find the category and attribute filters thatsearch_products accepts. Discovery is optional; an agent that already knows its filters can search directly. Taxonomy definitions describe valid vocabulary, not current inventory.
A typical sequence: call
taxonomy_tree without a node to pick a section, traverse that section, call taxonomy_attribute for the attributes you need, then pass the resulting filters to search_products as facets.
The REST equivalents are the Taxonomy API endpoints. To count products per category or value under a set of filters, call POST /v1/products/facet-counts; there is no MCP tool for counts.
Brand discovery tools
Usesearch_brands, similar_brands, brand_prefix, get_brand, browse_brand_products, and get_brand_top_categories to discover brands and browse their products. Brand identities describe makers and designers; they are distinct from stores and sellers. Discovery metadata is corpus-wide, while product browse respects your catalog scope. See Discover brands for arguments, response shapes, and examples.
Store discovery tools
Use these tools to find stores (retailers) by what they sell. Store profiles describe each store’s observed assortment, not live product availability. To find products at a store, callsearch_products with stores. The REST equivalents are the Stores API endpoints.
BigQuery subscription tools
Developer organizations can also use MCP to automate BigQuery subscriber registration and status refresh:
For most scheduled jobs, use the Python SDK’s
octogen-bq-autosubscribe command instead of calling these tools directly. See Subscribe to catalogs in BigQuery.
MCP vs REST API
Both surfaces are equally supported and enforce the same catalog policy. Developers can search and browse active crawled catalogs and cannot access merchant catalogs. BigQuery listings remain explicitly granted.
Both surfaces also share one per-organization rate limit: tool calls and REST API requests draw from the same budget.
Set up your client
Choose the guide for the AI tool you are using.Claude Code
Add StoreRouter to Claude Code with a single command and share the config with your team via
.mcp.json.Claude Desktop
Add StoreRouter as a custom connector in Claude Desktop or claude.ai.
Codex CLI
Register StoreRouter with Codex CLI and sign in once from the terminal.