Seekmodo

Seekmodo developer docs

Reference for the REST shim, MCP JSON-RPC surface, and storefront connectors. Authenticate with HMAC; replay window is 5 minutes.

Connectors

Pre-built plugins for the popular storefront platforms. Each plugin handles HMAC signing, the search swap-point, and the indexer cron for you. Building for a platform we do not ship? Start at Build a custom connector (vehicle / YMM: Vehicle fitment API). Platform-specific SEO guides live at /solutions — for example MediaWiki search and Magento 2 search.

Zen Cart
Available
Drop-in plugin for Zen Cart 1.5.7+. Swaps your storefront search over to Seekmodo and keeps the catalog in sync. Three modes — off, learning, active — let you cut over without surprises.
  1. Download the connector from your account portal once your trial is set up.
  2. Drop it into your Zen Cart's zc_plugins/ directory and visit Admin → Plugin Manager → Install.
  3. Click 'Connect to Seekmodo' in your store admin to pair the install with your Seekmodo account in one step (no API keys to copy).
  4. Run a week in 'learning' mode to verify, then flip to 'active'.

Full install guideTroubleshootingDownload & changelog

WordPress
Available
WordPress 6.2+ plugin for content sites and stores running WooCommerce. Auto-detects Custom Post Types and routes WP search through Seekmodo with WP_Query as the always-on fallback. Activates the bundled WooCommerce vertical automatically when WC is detected.
  1. Download the latest seekmodo-wordpress-*.zip from your account portal.
  2. WordPress admin → Plugins → Add New → Upload Plugin → choose the zip → Install Now → Activate.
  3. Open Settings → Seekmodo and click 'Connect to Seekmodo' — the plugin round-trips to seekmodo.com and pairs your tenant automatically.
  4. WP search now flows through Seekmodo with WP_Query as the always-on fallback. Run in 'learning' for a week, then flip to 'active'.
  5. If WooCommerce is installed on the same site, the commerce vertical auto-activates and indexes products on the next bulk-indexer tick (or run `wp seekmodo index --full`). No second plugin needed.

Full install guideTroubleshootingDownload & changelog

WooCommerce
Available
Native WooCommerce product search via the Seekmodo WordPress plugin: variation-aware, on-sale faceted, stock-aware. Same zip as the WordPress connector — install once, light up both verticals.
  1. Download the latest seekmodo-wordpress-*.zip from your account portal — WooCommerce ships inside the same WordPress connector zip.
  2. WordPress admin → Plugins → Add New → Upload Plugin → choose the zip → Install Now → Activate.
  3. On activation the plugin auto-detects WooCommerce. The commerce vertical lights up alongside the content vertical without any toggles.
  4. Open Settings → Seekmodo and click 'Connect to Seekmodo' to pair the tenant.
  5. Run `wp seekmodo index --full` (or wait for the bulk-indexer cron tick) to seed products, variations, brands, categories, and stock state into the gateway.
  6. Run in 'shadow' for a week to verify relevance against your top product searches, then flip to 'active'. WooCommerce's native `WC_Product_Query` stays armed as the always-on fallback.

Full install guideTroubleshootingDownload & changelog

Magento 2
Available
Magento 2.4+ module for Open Source and Adobe Commerce. Enhanced Native improves catalog search on install; pair for gateway AI search, multi-store indexing, and Growth-tier widgets.
  1. Download seekmodo-magento-v*.zip from seekmodo.com/plugins/magento or require via Composer: `composer require numinix/module-seekmodo`.
  2. Enable the module: `bin/magento module:enable Numinix_Seekmodo && bin/magento setup:upgrade && bin/magento cache:flush`.
  3. Admin → System → Seekmodo → Connect → Connect to Seekmodo to pair your tenant.
  4. Run `bin/magento seekmodo:index --full` to seed products and CMS pages per store view.
  5. Run in shadow mode for a week, then flip to active on admin.seekmodo.com. Native OpenSearch/Elasticsearch stays the degradation floor.

Full install guideDownload & changelog

BigCommerce
Beta
Official BigCommerce App Marketplace connector. OAuth install pairs your store to Seekmodo for AI search, vehicle fitment, VLPs, recommendations, and Script Manager storefront widgets.
  1. Install Seekmodo from the BigCommerce App Marketplace (or open https://bigcommerce-app.seekmodo.com/install from a store admin session).
  2. Allow the OAuth scopes (Information read-only, Products, Customers, Content).
  3. Complete pairing at seekmodo.com/connect — pick or create your Seekmodo tenant.
  4. Open Apps → Seekmodo to confirm pairing and wait for the first catalog index.
  5. Typeahead and Seekmodo search results are on by default after pairing and the first catalog index.
  6. Map custom fields in the admin iframe if your part numbers use merchant-specific names (e.g. EZ # → ez_number).

Full install guidePlugin overview

MediaWiki
Available
MediaWiki 1.39+ extension for knowledge bases. Routes Special:Search through Seekmodo (kb vertical) with native / CirrusSearch fallback, JobQueue indexing, typeahead, and LTR-ready click telemetry.
  1. Download seekmodo-mediawiki-v*.zip from seekmodo.com/plugins/mediawiki and extract into extensions/Seekmodo/.
  2. Add `wfLoadExtension( 'Seekmodo' );` to LocalSettings.php, then run `php maintenance/update.php`.
  3. Seed the index: `php extensions/Seekmodo/maintenance/SeekmodoIndex.php --full` then `php maintenance/runJobs.php`.
  4. As a sysop, open Special:Seekmodo → Connect to Seekmodo to pair your knowledge-base tenant.
  5. Special:Search now routes through Seekmodo with native / CirrusSearch as the always-on fallback.

Full install guideDownload & changelog

Shopify
Available
Official Shopify App Store connector. OAuth pairs your shop for AI catalog search, Theme App Extension widgets, vehicle fitment, VLPs, and Managed Pricing plans.
  1. Install Seekmodo from the Shopify App Store (or open https://shopify-app.seekmodo.com/auth).
  2. Approve OAuth scopes and choose a Managed Pricing plan (14-day trial available).
  3. Complete pairing at seekmodo.com/connect — pick or create your Seekmodo tenant.
  4. Online Store → Customize → App embeds → enable Seekmodo and Save (Shopify requires a merchant click).
  5. Optional: on the Search template, add the Seekmodo search-results app block and hide the theme's native Search results section.
  6. Wait for the first catalog index — status appears in Apps → Seekmodo.

Full install guidePlugin overview

Custom integration
Available
Roll your own connector for any CMS or commerce stack — HMAC REST / MCP, catalog sync, search, events, optional vehicle fitment. Full implementer guide plus interactive sandbox.
  1. Follow the full guide at /docs/connectors/custom — credentials, HMAC, index/search/events, MCP discovery, and optional vehicle fitment.
  2. Grab your tenant_id and shared secret at admin.seekmodo.com → Settings → Developer / API credentials. Rotate the secret any time; old keys stay valid for 10 minutes during rotation.
  3. Prefer a first-party SDK (JavaScript, PHP, Python, Ruby, Go) so you do not reimplement signing.
  4. Verify with POST /v1/tenant.handshake then POST /v1/search — see the Sandbox for live signed calls.
  5. Advertise the public (anonymous) MCP endpoint so AI agents can find your storefront — serve GET /.well-known/mcp.json and emit <link rel="mcp-server"> / <meta name="mcp-server"> in every page <head>. See Public MCP discovery below.
  6. Parts / YMM catalogs: also implement /docs/fitment (fits_vehicles, taxonomy upsert, search.by_vehicle).

Custom connector guideREST API referenceVehicle fitment APIPublic MCP discovery

Want to test a request without writing any code? Try the Sandbox — we sign with a demo tenant key on the server side.

Building a custom PHP storefront connector? The first-party Zen Cart and WordPress connectors all ship on top of the PHP SDK (composer require numinix/seekmodo-connector) — same HMAC + circuit-breaker + mode-FSM + pairing plumbing, ready to drop into your platform-specific glue.

Public MCP discovery

First-party connectors advertise an anonymous MCP endpoint so ChatGPT, Claude, Perplexity, Cursor, and similar agents can resolve "search this storefront" from the storefront URL alone. Custom connectors that own the storefront HTML (or can inject into <head>) should ship the same two surfaces. Hosted platforms that cannot write the site root (Shopify App Proxy, BigCommerce Script Manager without a theme edit) should still emit the head tags; /.well-known/mcp.json needs theme or docroot cooperation on those stacks.

The anonymous endpoint is always https://{tenant_id}.mcp.seekmodo.com/mcp— one tenant label before .mcp.seekmodo.com (do not substitute a regional authenticated host into this URL; that breaks anonymous wildcard routing). Emit discovery only when the connector is paired and mode is not off. Remove or stop advertising when the tenant is disconnected.

1. HTML <head> tags (required when you can inject markup)

<link rel="mcp-server"
      href="https://{tenant_id}.mcp.seekmodo.com/mcp"
      type="application/json"
      title="Seekmodo product search"
      data-discovery="https://{your-storefront}/.well-known/mcp.json">
<meta name="mcp-server"
      content="https://{tenant_id}.mcp.seekmodo.com/mcp">

2. GET /.well-known/mcp.json (required when you control the docroot or can route the path)

Serve JSON with Content-Type: application/json. A static file under the web root is fine; a dynamic route that returns the same payload is fine too. Example payload:

{
  "name": "Seekmodo product search",
  "description": "Read-only product catalog search for this storefront, provided by Seekmodo. Anonymous tier — no authentication, per-IP rate-limited.",
  "tenant_id": "{tenant_id}",
  "endpoints": [
    {
      "type": "mcp",
      "transport": "http",
      "url": "https://{tenant_id}.mcp.seekmodo.com/mcp",
      "auth": "none"
    }
  ],
  "tools": ["search"],
  "rate_limits": {
    "per_ip_per_minute": 60,
    "per_tenant_ip_per_day": 500,
    "notes": "Approximate defaults advertised for agents; the Seekmodo gateway enforces the live anonymous-tier budgets (env-configurable). A 429 with Retry-After is returned when the budget is exhausted."
  },
  "docs": "https://seekmodo.com/docs/mcp",
  "generator": "your-connector-id"
}

Verify with curl -sS https://{storefront}/.well-known/mcp.json and by confirming the homepage HTML contains rel="mcp-server". More on the anonymous tier and tool allowlist: MCP docs.