> ## Documentation Index
> Fetch the complete documentation index at: https://www.octogen.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Connect AI agents to StoreRouter via MCP
> Let AI coding tools search and look up products in your granted StoreRouter catalogs using the Model Context Protocol — no API keys required.
The StoreRouter Developer MCP server gives AI agents direct access to the product catalogs granted to your organization. Agents running inside Claude Code, Codex CLI, Claude Desktop, or any MCP-compliant client can call catalog lookup/search tools and BigQuery subscription tools without you needing to provision API keys, client IDs, or shared secrets. Authentication is handled through a browser sign-in the first time a tool is called; after that, tokens are cached and refreshed transparently.
## Connection details
| Property | Value |
| - | - |
| Base URL | `https://mcp.octogen.ai/mcp` (Codex CLI uses `https://codex-mcp.octogen.ai/mcp`) |
| Transport | Streamable HTTP |
| Auth | OAuth 2.1 with PKCE-S256 against `https://auth.octogen.ai` |
| Discovery | RFC 9728 protected-resource metadata at `https://mcp.octogen.ai/.well-known/oauth-protected-resource` |
## Authentication
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 Octogen 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 stored locally.
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.
## Prerequisites
Both conditions must be true before your first tool call.
* Your organization is provisioned as a Developer organization. If you do not yet have a Developer organization, contact StoreRouter support.
* 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](/docs/api-reference/overview), so access control is consistent across surfaces.
### `lookup_product(product_url, catalogs?)`
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. If no active product matches, the tool returns a structured `product_not_found` value — not a transport-level failure — so your agent can recover gracefully.
### `search_products(catalog, query?, limit?, cursor?)`
Searches products inside one active crawled catalog by free-text keyword. Use a known catalog key. Results are paginated; pass the `nextCursor` from one response as `cursor` on the next call to advance. The `limit` parameter accepts values from 1 to 100 (default 50); values outside that range return a structured `invalid_limit` error.
## BigQuery subscription tools
Developer organizations can also use MCP to automate BigQuery subscriber registration and status refresh:
| Tool | Purpose |
| - | - |
| `list_bigquery_listing_resources` | Lists BigQuery Analytics Hub listings granted to your organization. |
| `list_bigquery_subscribers` | Lists registered subscriber projects, principals, and per-catalog status cells. |
| `register_bigquery_subscriber` | Registers the GCP project and principal that should receive Analytics Hub subscriber access. |
| `refresh_bigquery_subscription_status` | Checks whether a linked dataset subscription exists and updates StoreRouter status. |
| `delete_bigquery_subscriber` | Disables a registered subscriber. |
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](/docs/guides/bigquery-subscribe).
## 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.
| | Platform Catalog API v1 (API keys) | MCP (OAuth) |
| - | - | - |
| Best for | Backends, batch jobs, server-to-server | Interactive AI agents (Claude Code, Codex CLI, Claude Desktop) |
| Auth | Bearer `octo_live_...` key | OAuth 2.1 + PKCE — browser sign-in, tokens cached locally |
| Caller identity | `(api_key_id, org_id)` | `(user_sub, org_id, oauth_client_id)` |
| Token lifetime | Until manually revoked | \~5 minutes access; refresh until session expiry |
| Revocation | Revoke the API key | Sign out of StoreRouter Platform or remove user from org |
Both surfaces also share one per-organization [rate limit](/docs/guides/rate-limits): 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.
Add StoreRouter to Claude Code with a single command and share the config with your team via `.mcp.json`.
Connect Claude Desktop using the `mcp-remote` adapter and a one-time JSON config change.
Register StoreRouter with Codex CLI using its dedicated compatibility endpoint.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.