Connect AI agents to Octogen via MCP

The Octogen 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

​

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 Octogen sign-in session is active. To end access, sign out of the Octogen Platform or have your organization administrator remove your account.

​

Prerequisites

• Your organization is provisioned as a Developer organization. If you do not yet have a Developer organization, contact Octogen support.
• You can sign in to the Octogen 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, 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: 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.