Seekmodo developer docs
Reference for the REST shim, MCP JSON-RPC surface, and storefront connectors. Authenticate with HMAC; replay window is 5 minutes.
Model Context Protocol (MCP)
Seekmodo speaks the Model Context Protocol so AI clients like Claude Desktop, Cursor, and ChatGPT can read and write your search configuration on your behalf — discovering zero-result queries, proposing synonyms, pinning products, and tuning ranking — with a human approving every change. For a merchant-facing overview, see the MCP catalog search guide or the broader AI site search overview.
Already a Seekmodo customer?
Open the AI prompt library in your admin to copy ready-to-paste workflows for your AI assistant — or connect Claude / Cursor directly with an operator token.
Connect an AI agent (Claude, Cursor, and friends)
Two paths — pick whichever matches how you work. Both start in admin.seekmodo.com → Settings → AI Integration.
Path A — Wire Claude Desktop or Cursor (recommended)
This lets the AI call Seekmodo tools for you (search telemetry, synonyms, playbooks) while you approve every write.
- Click Mint token. Label it (e.g.
cursor-laptop). Copy the raw token — it is shown once. - Copy the client snippet from the mint modal (Cursor / Claude Desktop / Cline / Continue tabs).
- Paste it into your client's MCP config:
- Cursor:
~/.cursor/mcp.json(Windows:%USERPROFILE%\.cursor\mcp.json) - Claude Desktop:
claude_desktop_config.jsonunder AppData (Windows) or Application Support (macOS)
- Cursor:
- Fully quit and reopen the app. In Cursor the MCP panel should show your Seekmodo server as ready; in Claude type
/to see Seekmodo playbooks. - Smoke-test: ask “List my Seekmodo tools” or run
/fix-zero-results.
Full snippets, scopes (operator-readonly vs operator), troubleshooting, and playbook walkthroughs: Connect Claude or Cursor runbook.
Path B — No MCP install (plain ChatGPT / Claude.ai / Gemini)
When you see a banner such as “Suggested next: Run fix-zero-results” with Run in Claude / Copy:
- Copy puts a ready-made prompt on your clipboard — paste it into any chat AI. The AI will walk you through the playbook and ask you to pull data from admin pages as it goes (no gateway token required).
- Run in Claude is the shortcut once Claude Desktop is connected via Path A above — it opens the playbook against your live tenant.
You can also open the prompt library anytime and hit Copy prompt for any playbook.
Storefront discovery (public AI agents)
Shopper-facing AI agents resolve a storefront's Search MCP endpoint from the storefront URL — not from mcp.seekmodo.com alone. First-party connectors and custom connectors must advertise:
GET https://{storefront}/.well-known/mcp.jsonpointing athttps://{tenant_id}.mcp.seekmodo.com/mcp(auth: none), and<link rel="mcp-server">plus<meta name="mcp-server">in every storefront<head>.
That anonymous host accepts unauthenticated JSON-RPC for a tight allowlist (primarily search and tenant.handshake), with per-IP rate limits. Full payload shape and implementation notes live on the connectors · Public MCP discovery section. Authenticated operator / connector traffic stays on https://mcp.seekmodo.com/mcp with HMAC or an operator bearer token.
Calling the gateway directly
For server-to-server integrations, the gateway speaks JSON-RPC 2.0 at POST https://mcp.seekmodo.com/mcp. Send tools/list to discover what your tenant can call, and tools/call to invoke a tool. The same tools are also POST /v1/<tool.name> over REST — interactive request schemas live in the REST OpenAPI reference. Tenant API calls use the HMAC headers documented there; operator workflows authenticate with a bearer token minted from your admin.
POST /mcp HTTP/1.1
Host: mcp.seekmodo.com
Content-Type: application/json
X-Seekmodo-Tenant: ten_...
X-Seekmodo-Timestamp: 1717000000
X-Seekmodo-Nonce: 9f3a...
X-Seekmodo-Signature: ...
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list",
"params": {}
}Tool catalog
Live from the gateway · last refreshed Tue, 08 Sep 2026 03:47:36 GMT · 89 available, 1 preview. available= generally available on every plan that includes the surface · preview= name reserved, implementation on the roadmap.
Search
| Tool | Description | Mutates | Status |
|---|---|---|---|
| search | Read-only corpus search. Body params are passthrough to the per-tenant Typesense collection. | no | available |
| search.by_vehicle | Vehicle-id-scoped corpus search. Returns products whose `fits_vehicles` int[] contains the requested vehicle_id. | no | available |
| search.byImage | Image-as-query corpus search. Accepts one of {image_b64, image_url, doc_id} and returns SKUs visually similar to the query via CLIP ViT-B/32 + Typesense vector_query. | no | available |
| suggest | Typeahead suggestions: prior-search keywords, prefix-matched products, and matching categories. | no | available |
| typeahead | Flat-row typeahead for storefront connectors. Returns N prefix-matched docs from the tenant Typesense collection in the legacy {rows} shape WP / Zen Cart connectors expect. | no | available |
Catalog & telemetry
| Tool | Description | Mutates | Status |
|---|---|---|---|
| events | Record search / click / impression events for analytics, LTR training, and bot-check verdict tagging. | yes | available |
| index | Bulk upsert documents into the tenant's Typesense collection. Mirrors the documents/import wire shape. | yes | available |
| tenant.catalog_preview | Return a small sample of indexed documents (admin only). With `q`, runs a prefix-match autocomplete used by the admin doc picker. | no | available |
| tenant.domain.promote | Self-service swap of the tenant's canonical storefront host. Used by connectors to flip from dev -> prod without an operator round-trip. | yes | available |
| tenant.handshake | Verify connector configuration and discover the tenant's tool surface, vertical, and rate limits. | no | available |
| tenant.region.list | Read tenant-level multi-region flags + every numinix_mcp_tenant_regions row. | no | available |
| tenant.snapshot | Read (or push to) the full tenant runtime config snapshot. | no | available |
Merchandising
| Tool | Description | Mutates | Status |
|---|---|---|---|
| banners.list | List banner merchandising rules for the tenant. | no | available |
| banners.remove | Delete a banner merchandising rule by id. | yes | available |
| banners.set | Create or update a banner merchandising rule. | yes | available |
| deboosts.list | List deboost merchandising rules for the tenant. | no | available |
| deboosts.remove | Delete a deboost merchandising rule by id. | yes | available |
| deboosts.set | Create or update a deboost merchandising rule. | yes | available |
| pins.landscape | Snapshot of active pin rules with priority, schedule, audience, and metadata. | no | available |
| pins.list | Read editorial pins for the tenant. | no | available |
| pins.remove | Delete a pin entry by id. | yes | available |
| pins.set | Pin or exclude documents for a specific query. | yes | available |
| redirects.list | List keyword redirect merchandising rules for the tenant. | no | available |
| redirects.propose | Propose keyword redirect rules from search telemetry (dry-run only). | no | available |
| redirects.remove | Delete a keyword redirect merchandising rule by id. | yes | available |
| redirects.set | Create or update a keyword redirect merchandising rule. | yes | available |
| segments.list | List customer segments for the tenant. | no | available |
| segments.remove | Delete a customer segment by id. | yes | available |
| segments.set | Create or update a customer segment. | yes | available |
| synonyms.add | Add or replace a synonym entry. id is optional; we generate one if omitted. | yes | available |
| synonyms.list | Read the per-tenant synonym list. Returns Typesense-native synonym entries. | no | available |
| synonyms.remove | Delete a synonym entry by id. | yes | available |
Analytics
| Tool | Description | Mutates | Status |
|---|---|---|---|
| analytics.click_pain | High-volume queries with deep average click position (>=5). Highest-leverage pin / reranker candidates. | no | available |
| analytics.conversion_funnel | Daily funnel (searches -> clicks -> add_to_carts -> purchases) plus session-scoped conversion rates. | no | available |
| analytics.ctr_trend | Daily CTR over a rolling window — aggregate (default) or per top-N keyword. | no | available |
| analytics.latency | Per-tenant search latency (p50, p95) and fallback rate over a rolling window for the operator health card. | no | available |
| analytics.revenue_by_query | Per-keyword revenue + order count for a rolling window, under a chosen attribution model. | no | available |
| analytics.search_types | Search volume breakdown by type (keyword, vehicle/YMM, hybrid) for a rolling window. | no | available |
| analytics.top_clicked_products | Most-clicked products with click counts and top driving keywords for a rolling window. | no | available |
| analytics.top_queries | Most-searched keywords with CTR and avg result count for a rolling window. | no | available |
| analytics.weekly_digest | Weekly search digest JSON for email reports (KPIs, keywords, products, zero-results, funnel, latency). | no | available |
| analytics.zero_results | Search queries that returned zero results. | no | available |
| catalog.get | Fetch a single indexed catalog document by id or sku with rich default fields. | no | available |
| catalog.prune | Delete commerce catalog documents whose last_indexed_at is strictly older than the supplied cutoff. Called after a successful full index run so hard-deleted or otherwise absent products stop appearing in suggest/typeahead. | yes | available |
| catalog.stats | Corpus size, schema fingerprint, top-K category breadcrumbs. Read-mostly catalog metadata. | no | available |
Recommendations
| Tool | Description | Mutates | Status |
|---|---|---|---|
| bundle.suggest | Anchor-based "complete the kit" bundle composer using co_purchase + diversity bias. | no | available |
| recommend.also_bought | Anchor-anchored frequently-bought-together recommendations from co-purchase signal with lexical fallback. | no | available |
| recommend.also_viewed | Anchor-anchored also-viewed recommendations from broad same-session signal with lexical fallback. | no | available |
| recommend.related | Anchor-anchored related-products recommendations from co-view signal with lexical fallback. | no | available |
| recommend.trending | Non-anchored trending products recommendation (last-30-day co-occurrence aggregation). | no | available |
A/B testing
| Tool | Description | Mutates | Status |
|---|---|---|---|
| ab.archive | Archive an experiment without promoting any variant. | yes | available |
| ab.create | Create a new A/B experiment with at least two variants. | yes | available |
| ab.list | List A/B experiments for the tenant. | no | available |
| ab.promote | Promote a winning variant of a running A/B experiment. | yes | available |
| ab.results | Per-variant impression / click / CTR rollup for an experiment. | no | available |
Learning-to-rank
| Tool | Description | Mutates | Status |
|---|---|---|---|
| ltr.config.set | Patch per-tenant LTR settings (management, mode, ab_ramp_pct, etc). | yes | available |
| ltr.diagnostics | Snapshot of LTR pipeline health: scorer reachability, linked-click coverage, filter diversity, AGREE-rate, arm CTR. | no | available |
| ltr.model.rollback | Operator action: roll the tenant back to a previously trained LTR model. Requires a free-text reason. | yes | available |
| ltr.retrain | Force-retrain the LTR model now. Returns the new model summary. | yes | available |
| ltr.shadow_deltas | List recent shadow-mode disagreements between LambdaMART and the served top-1 for operator gut-check. | no | available |
| ltr.shadow_feedback | Record operator gut-check (thumbs up/down) on a shadow-mode LambdaMART disagreement. | yes | available |
| ltr.status | Read LTR settings, the active model summary, and recent training runs. | no | available |
| ltr.toggle | Toggle Learning-to-Rank on or off for the tenant. | yes | available |
Bot defence
| Tool | Description | Mutates | Status |
|---|---|---|---|
| bot_check.status | Per-tenant bot-check status: enrollment, last activity, and 24-hour bot-blocked counts. | no | available |
| bot.classify | Classify a request triple (UA + IP + session) as bot or human; returns bot_score 0..100 + reasons + signal breakdown. | no | available |
| bot.health | Bot-check inline classifier health: 5-min classify volume (inline vs http), nonce issue/verify rates, 24h shadow AGREE-rate. | no | available |
| nonce.issue | Issue an HMAC nonce for the SERP click-beacon flow. | no | available |
| nonce.verify | Verify an HMAC nonce for the SERP click-beacon flow; returns valid bool + age + reason. | no | available |
Shopper UX
| Tool | Description | Mutates | Status |
|---|---|---|---|
| chat | Conversational shopper assistant. Runs an LLM-driven loop that issues sub-tool calls (search, suggest, recommend) and returns a cited natural-language answer. | no | available |
Fitment & vehicles
| Tool | Description | Mutates | Status |
|---|---|---|---|
| fitment.assignments.bulk_upsert | Bulk-upsert per-tenant product fitment assignments against central seekmodo_vehicle_id values. | yes | available |
| fitment.assignments.changes | Return per-tenant fitment assignment rows changed since updated_since (ISO-8601). | no | available |
| fitment.coverage | Coverage aggregates over numinix_mcp_vehicle_taxonomy for the tenant. | no | available |
| fitment.import.csv | Import fitment assignments from CSV text. Resolves YMM to central catalog (auto-creates merchant_import vehicles when missing). | yes | available |
| fitment.orphans | Vehicles with zero fitted products (product_count=0) for the tenant. | no | available |
| fitment.overrides.list | Paginated list of per-tenant fitment overrides (operator-set add/remove rules layered on top of the AutoPro fitment graph). | no | available |
| fitment.resolve | Resolve a (year, make, model) triple against the per-tenant vehicle taxonomy projection into a concrete vehicle_id + canonical label. Returns null when no row matches. | no | available |
| vehicle_taxonomy.bulk_upsert | Bulk-upsert vehicle taxonomy rows (year/make/model + pre-computed VLP slug + product_count) into the per-tenant projection. Up to 1000 rows per call. Called by the connector's seekmodo:vlp-project artisan command. | yes | available |
| vehicle_taxonomy.prune | Delete vehicle taxonomy rows whose last_seen_at is older than the supplied UTC cutoff (ISO 8601). Called after a successful seekmodo:vlp-project run so vehicles that disappear from the connector's projection stop appearing in the gateway sitemap. | yes | available |
| vehicle.taxonomy.lookup | Resolve a per-tenant vehicle taxonomy row by VLP slug (e.g. "keys-for-2019-honda-civic") or by vehicle_id. Returns the canonical row used by the BC Worker VLP renderer. | no | available |
| vehicle.taxonomy.neighbours | Return the two AKS-canonical neighbour lanes (same make+model different year; same year+make different model) for a given vehicle_id in the per-tenant projection. | no | available |
| vehicles.catalog.changes | Return central vehicle catalog rows changed since updated_since (ISO-8601). Supports cursor pagination. | no | available |
| vehicles.catalog.lookup | Resolve year/make/model (and optional engine_trans_code) against the central Seekmodo vehicle catalog. | no | available |
| vehicles.picker.options | Return cascading YMM picker options for vehicles that have at least one product assignment for this tenant. | no | available |
ESP integrations
| Tool | Description | Mutates | Status |
|---|---|---|---|
| esp.dlq_recent | Recent ESP DLQ rows for the admin failure-visibility surface. | no | available |
| esp.test_event | Fire a synthetic event at the configured ESP and return the provider verdict synchronously. | yes | available |
Commerce
| Tool | Description | Mutates | Status |
|---|---|---|---|
| commerce.boost_by_stock | Set stock_ranking_policy=demote_all_oos via tenant.config.set. | yes | available |
| commerce.exclude_out_of_stock | Set stock_ranking_policy=exclude_all_oos via tenant.config.set. | yes | available |
| commerce.promotions.list | List active commerce promotions. | no | preview |
Other
| Tool | Description | Mutates | Status |
|---|---|---|---|
| ask | Single-turn Ask AI over the tenant catalog and policy docs. Bounded search + catalog.get loop with cited answers. | no | available |
| resolve_redirect | Resolve a shopper query to a merchandising redirect URL, if any. | no | available |