Seekmodo

Seekmodo developer docs

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

← Back to Connectors

Build a custom Seekmodo connector

First-party plugins cover Zen Cart, WordPress / WooCommerce, Magento 2, BigCommerce, MediaWiki, and Shopify. Everything else — PrestaShop, Drupal Commerce, OpenCart, custom PIMs, headless storefronts, and internal tools — pairs through the same gateway using HMAC-signed REST (or MCP). This page is the implementation contract for third-party and in-house connector authors.

Product / SEO overviews live under /solutions. Interactive request schemas: REST OpenAPI (deep-linked from tool names below) · live tool catalog: MCP · try calls in the Sandbox.

1. Credentials and HMAC

  1. Create a tenant at seekmodo.com/signup and open admin.seekmodo.com → Settings → Developer / API credentials.
  2. Copy tenant_id and the shared secret. Rotate anytime; old secrets stay valid for 10 minutes.
  3. Sign every authenticated request with:
    • X-Seekmodo-Tenant — tenant id
    • X-Seekmodo-Timestamp — Unix seconds (±5 minute replay window)
    • X-Seekmodo-Signature — HMAC-SHA256 of the raw HTTP body with the tenant shared secret (hex digest)

Prefer a first-party SDK so you do not reimplement signing: SDK hub (JavaScript, PHP, Python, Ruby, Go). Gateway host: https://mcp.seekmodo.com. Auth details also open the REST intro at /docs/rest.

2. Minimal integration loop

  1. POST /v1/tenant.handshake (or MCP tenant.handshake) — confirm credentials.
  2. POST /v1/index — upsert catalog documents (max 1,000 per call; use documents or legacy docs).
  3. POST /v1/search with a known query — expect ranked hits within tens of milliseconds once the index is warm.
  4. POST /v1/events — batch shopper search / click / add_to_cart / purchase rows so relevance can learn.

REST path shape: every MCP tool is also POST https://mcp.seekmodo.com/v1/<tool.name>. List tools with GET /v1/tools (authenticated), GET /v1/tools/public, or see /docs/mcp.

3. Catalog index and prune

Push products (and optional content docs) with index. Stamp or rely on gateway last_indexed_at, then after a full sync call catalog.prune with a cutoff so deleted SKUs leave the collection. Chunk large catalogs; never send more than 1,000 documents per request. Schemas: Catalog & telemetry in REST.

Minimum useful product fields:

  • id — stable product / document id
  • title / name, description, URL, image URL
  • Price, stock, categories / facets your SERP needs
  • For parts catalogs: fits_vehicles (int array) and optional universal_fit (bool) — see Vehicle fitment guide
  • search — full results page queries
  • suggest — typeahead dropdown
  • typeahead — flat-row connector typeahead when you own the response shape

Forward shopper session_id, ua, and ip on search/suggest so bot-check and learning stay accurate. Browser UIs can mint a short-lived JWT via POST /v1/tenants/token and use @seekmodo/sdk or web components without exposing the shared secret. REST tag: Search.

5. Telemetry and learning

Batch events with events (up to 200 per call). Link clicks and conversions to the originating search with search_event_id from the search response when available. Include product_id, position, and for commerce qty / price_cents / order_id on cart and purchase events.

6. Modes and domain lock

Connectors typically run learning / shadow before active so native platform search remains the degradation floor. When the tenant has a locked production storefront host, send X-Seekmodo-Storefront-Host and keep index writes on the canonical host — see tenant settings.

7. Public MCP discovery (agents)

So ChatGPT, Claude, Cursor, and similar agents can find your catalog from the storefront URL, advertise the anonymous MCP endpoint when the tenant is paired and not in off mode:

  • HTML <head>: rel="mcp-server" link + meta name="mcp-server"
  • GET /.well-known/mcp.json on the storefront origin

Endpoint URL shape: https://{tenant_id}.mcp.seekmodo.com/mcp. Full payload example: Connectors → Public MCP discovery. Product overview: MCP catalog search.

8. Vehicle / YMM fitment (optional)

Automotive and parts connectors index fits_vehicles, sync a per-tenant vehicle taxonomy, and call fitment.resolve + search.by_vehicle. VIN decode stays in your connector (e.g. NHTSA vPIC) — resolve to a vehicle id, then use the same search path. Full guide: /docs/fitment. REST tag: Fitment & vehicles.

9. Recommendations

After catalog + events are flowing, call recommend.related, recommend.also_bought, recommend.also_viewed, or recommend.trending. With a garage vehicle, AND fitment via filter_by such as fits_vehicles:=123 || universal_fit:=true. REST tag: Recommendations.

10. Verification checklist

  • Handshake succeeds; secret rotation does not hard-fail mid-window.
  • Index + prune leave search results matching the live catalog.
  • Suggest and search work with native fallback when you simulate gateway downtime.
  • Click / ATC / purchase events appear in admin analytics for the tenant.
  • /.well-known/mcp.json returns JSON and homepage HTML includes rel="mcp-server".
  • Parts catalogs: search.by_vehicle returns fitted SKUs; empty responses with meta.fits_vehicles_unavailable mean the collection is missing the fitment field.

Marketplace submissions (roadmap)

A public submission flow for listing third-party connectors on seekmodo.com is planned. Until then, ship against this contract, keep your connector versioned, and contact us if you want early listing review.