Skip to main content
The StoreRouter MCP server gives AI agents direct access to product, brand, and store data across the stores StoreRouter covers. Agents running inside Claude Code, Claude (web and desktop), Codex CLI, or any MCP-compliant client can call product lookup and search, taxonomy, brand, store, and BigQuery subscription tools. Interactive clients authenticate through a browser sign-in the first time a tool is called, with no API keys, client IDs, or shared secrets to provision; after that, tokens are cached and refreshed transparently. Clients that run as a service, with nobody there to sign in, can send your organization’s API key instead; see Server-side integrations.

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:
  1. On the first tool call, your client opens a browser tab pointed at the StoreRouter sign-in page.
  2. 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.
  3. You consent to the requested scopes.
  4. The browser redirects back to your client, which exchanges the authorization code for an access token and a refresh token.
Access tokens are valid for approximately five minutes. Refresh happens transparently in the background as long as your StoreRouter sign-in session is active. To end access, sign out of the StoreRouter Platform or have your organization administrator remove your account.

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:
For example, to list the tools with curl, reading the key from the environment:
It is the same key you use with the Platform Catalog API v1, with the same limits and metering. There is no separate MCP key. Tool calls share your organization’s rate limit with REST requests. 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.
Your API key is an organization credential: anyone holding it can make billed requests for your organization. Keep it in an environment variable or secret manager, never in a committed client config. Treat MCP client logs as sensitive, because a client that logs request headers logs the key. If a key leaks, revoke it in StoreRouter Platform under API Keys and create a new one.

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:
Unknown or inaccessible catalog keys match no products. An uncovered store domain returns domain_not_covered. Selectors only narrow your organization’s access; they cannot grant access to merchant catalogs.

Search response

The tool’s structuredContent is the REST page itself, with requestId, items, nextCursor, and effectiveQuery. For example, an empty browse page is:
Read 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 only cursor 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 with isError: 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 that search_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

Use search_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, call search_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.