Seekmodo

Seekmodo developer docs

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

AI Integration — mint a token, wire your AI client

Seekmodo's gateway speaks the Model Context Protocol. Once you mint a bearer token and paste the config snippet below into your AI client, your AI can call into your Seekmodo tenant directly — reading search telemetry, proposing synonyms, running Seekmodo's built-in optimisation playbooks — without you having to round-trip through us.

The whole flow takes about three minutes:

  1. Mint a token in admin.
  2. Pick your client (Claude Desktop, Cursor, Cline, Continue, or raw cURL) and paste the snippet.
  3. Smoke-test with the bundled curl example.
  4. Run a playbook — /fix-zero-results is a good first one.

1. Mint a token

  1. Open admin.seekmodo.com → Settings → AI Integration.
  2. Click Mint token. Give it a label so you remember which AI client it belongs to (e.g. cursor-laptop).
  3. Copy the raw token from the modal. It is shown once; if you close the modal without copying, you have to revoke it and mint a new one.

New tokens default to the operator-readonly scope, which lets the AI read your search telemetry but forbids any mutating tool call (no synonyms.add, no index, no ltr.retrain). Flip to the operator scope from the token row once you've verified the AI behaves as expected — most merchants leave the first token in operator-readonly and mint a second, scoped operator token for applying changes.

2. Wire your AI client

Every snippet below assumes you copied the raw token in step 1; replace <PASTE_TOKEN_HERE> with that value and <YOUR_TENANT_ID> with the slug you see at the top of the admin page (e.g. acme).

Cursor 1.0+ and recent Claude Desktop builds speak HTTP MCP natively — the url + headers shape below is all you need, no mcp-remote npx shim, no environment-variable plumbing. If you're still on an older client that only supports stdio MCP, jump to the mcp-remote fallback section below.

Each tenant gets its own unique server name in mcpServers — shaped like seekmodo-<display-name-slug>-<tenant-id> (for example seekmodo-numinix-com-jlew-00e070bd). The mint modal generates this for you. When you run multiple storefronts on one laptop, merge each snippet as a new key; reusing the same key replaces the previous tenant.

Cursor IDE (1.0+) — recommended

Save the following to ~/.cursor/mcp.json (Windows: %USERPROFILE%\.cursor\mcp.json). If the file already exists, merge the inner mcpServers key:

{
  "mcpServers": {
    "seekmodo-numinix-com-jlew-00e070bd": {
      "url": "https://mcp.seekmodo.com/mcp",
      "headers": {
        "Authorization": "Bearer <PASTE_TOKEN_HERE>",
        "X-Seekmodo-Tenant": "jlew-00e070bd"
      }
    }
  }
}

Fully restart Cursor (close every window, not just reload). The MCP panel in the sidebar should show your server key (for example seekmodo-numinix-com-jlew-00e070bd) as ready with around two dozen tools listed.

If it shows as “failed to load” with no inline output, the underlying handshake error is hidden in the Output panel. Open it with Ctrl+Shift+U (Cmd-Shift-U on macOS), then in the dropdown pick MCP Logs. Look for the line tagged with your server key (for example seekmodo-numinix-com-jlew-00e070bd). The common failure modes:

  • 401 bad_operator_token_format — token isn't shaped seekmodo_op_ + 26 uppercase base32 chars. Re-copy from the admin row (no trailing whitespace).
  • 401 operator_token_revoked — mint a fresh token; revocation takes effect immediately.
  • 401 operator_token_tenant_not_whitelisted — the X-Seekmodo-Tenant header doesn't match a tenant the token has access to. Check the slug (e.g. acme, not ACME or acme.seekmodo.com).
  • No log line at all for your server key — the JSON is invalid. Run it through any JSON linter (a stray trailing comma is the usual culprit).

Claude Desktop

Open ~/Library/Application Support/Claude/ claude_desktop_config.json on macOS, or %APPDATA%\Claude\claude_desktop_config.json on Windows. Merge this under the existing mcpServers object (or create it if the file is empty):

{
  "mcpServers": {
    "seekmodo-numinix-com-jlew-00e070bd": {
      "url": "https://mcp.seekmodo.com/mcp",
      "headers": {
        "Authorization": "Bearer <PASTE_TOKEN_HERE>",
        "X-Seekmodo-Tenant": "jlew-00e070bd"
      }
    }
  }
}

Quit Claude Desktop fully (Cmd-Q on macOS — closing the window isn't enough). On relaunch, type / in any chat to see Seekmodo's playbooks pop up alongside Claude's built-in slash commands.

Cline (VS Code extension)

Open VS Code's user settings.json (Cmd-Shift-P → Preferences: Open User Settings (JSON)) and merge this block at the top level:

{
  "cline.mcpServers": {
    "seekmodo-numinix-com-jlew-00e070bd": {
      "url": "https://mcp.seekmodo.com/mcp",
      "headers": {
        "Authorization": "Bearer <PASTE_TOKEN_HERE>",
        "X-Seekmodo-Tenant": "jlew-00e070bd"
      }
    }
  }
}

Reload VS Code (Cmd-Shift-P → Developer: Reload Window). Cline picks up the new MCP server on next chat.

Continue (VS Code / JetBrains)

Edit ~/.continue/config.json and merge:

{
  "mcpServers": {
    "seekmodo-numinix-com-jlew-00e070bd": {
      "url": "https://mcp.seekmodo.com/mcp",
      "headers": {
        "Authorization": "Bearer <PASTE_TOKEN_HERE>",
        "X-Seekmodo-Tenant": "jlew-00e070bd"
      }
    }
  }
}

Reload your editor (VS Code or JetBrains). Continue exposes the Seekmodo tools alongside any other MCP servers you have configured.

Fallback: stdio clients via mcp-remote

Some older AI clients only support stdio MCP (a child process the client spawns), not HTTP. The mcp-remote npx shim bridges the gap by speaking stdio on one side and HTTP on the other. Only use this shape if the native url + headers config above produces a “remote MCP not supported” error in your client's logs.

{
  "mcpServers": {
    "seekmodo-numinix-com-jlew-00e070bd": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.seekmodo.com/mcp",
        "--header",
        "Authorization:${SEEKMODO_MCP_AUTH}",
        "--header",
        "X-Seekmodo-Tenant:${SEEKMODO_MCP_TENANT}"
      ],
      "env": {
        "SEEKMODO_MCP_AUTH":   "Bearer <PASTE_TOKEN_HERE>",
        "SEEKMODO_MCP_TENANT": "<YOUR_TENANT_ID>"
      }
    }
  }
}

Known Windows gotcha. Cursor and Claude Desktop on Windows have historically word-split args entries that contain spaces, dropping the header silently. The literal ${VAR} substitution above happens after arg-splitting and works around that bug, but the native url + headers shape above sidesteps the issue entirely and is the better choice on Windows.

Raw cURL (smoke test)

Before wiring any AI client, run this to confirm the token and tenant header round-trip cleanly. A 200 with serverInfo in the body means you're done with auth setup:

curl -sS -X POST 'https://mcp.seekmodo.com/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <PASTE_TOKEN_HERE>' \
  -H 'X-Seekmodo-Tenant: <YOUR_TENANT_ID>' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","clientInfo":{"name":"curl-smoke","version":"1.0"},"capabilities":{}}}'

Common failure modes:

  • 401 — token mismatch. Re-copy from the admin token row (most likely cause: trailing space).
  • 403 with tenant_not_found — the X-Seekmodo-Tenant header doesn't match a tenant you have access to. Check the slug.
  • 429 — rate limit. The default per-token ceiling is 500 calls/hour; the same token can fan out to multiple regions but a per-region cap applies (see Regions).

3. Verify it's wired up

From your AI client, ask any of the following — every client should answer without an HTTP error:

  • “List my Seekmodo tools.” — should enumerate around 24 tools, including search, synonyms.list, analytics.zero_results, and ltr.retrain.
  • “Show the top 5 zero-results queries from the last 30 days.” — calls analytics.zero_results; gives you a feel for how the AI surfaces tool output.

4. Run a playbook

Seekmodo ships six built-in playbooks that the AI can execute end-to-end. The first one most merchants run:

Run the fix-zero-results playbook for my tenant. Apply the
synonyms it recommends, but stop and ask me before any
synonyms.add call so I can sanity-check the substitutions.

The agent will:

  1. Call prompts/get fix-zero-results to read the playbook's system prompt.
  2. Call analytics.zero_results --since_days 30 and group queries the AI thinks share a synonym root.
  3. Surface a candidate list and stop (your “ask before applying” prompt forces this).
  4. After your confirmation, call synonyms.add for each candidate. Each call writes one row to your tenant's audit log.
  5. Re-run analytics.zero_results over the last day to verify the synonyms made a dent.

Other playbooks worth running once your traffic has signal: /audit-fitment (catalog quality), /retrain-ltr (re-train learn-to-rank on the last 30 days of clicks), /dial-relevance (test alternate weights against your current ranker without committing).

Running a playbook without MCP (ChatGPT, Claude.ai, Gemini)

Wiring up MCP is the gold path — the AI calls your tenant directly, you approve mutations, and the audit log captures every write. But if you just want to try a playbook in ChatGPT, Claude.ai, Gemini, or any other plain-chat AI:

  1. Open admin.seekmodo.com → Settings → AI Integration → Open prompt library.
  2. Pick a playbook and hit Copy prompt. The copied text includes a preamble that tells the AI it is operating without a live MCP connection and should ask you for tool-result data as it works.
  3. Paste the prompt into a new chat. The AI walks you through each step and tells you which admin page or storefront query to pull data from.

This path is interactive and slower than the wired-up MCP path (you fetch data manually instead of the AI fetching it), but it is a zero-setup way to try a playbook against a real tenant. Tenants that like the workflow usually graduate to an MCP-aware client (Cursor, Claude Desktop) after the first successful run.

5. Customise a playbook (optional)

Every playbook ships with a sensible default, but you can override the system prompt per-tenant when your business rules differ. Examples: locksmiths who need transponder synonyms treated as exact-match boosts, or fashion stores who want the AI to skip color-only zero-results queries because their merchandiser handles those manually.

  1. Open Settings → AI Integration → Playbooks.
  2. Pick the playbook you want to customise. The right pane shows the default prompt; the left pane is your override.
  3. Paste or edit the override. The validator runs on save — it rejects prompts with disallowed tool names, missing required hand-off sentences (the “stop and ask before applying any change” line is non-negotiable), or templating errors.
  4. Save. The override takes effect on the next prompts/get call from any AI client.

Overrides version automatically; the four most recent snapshots are kept and one-click-revertable from the playbook's history drawer.

Rotation & revocation

Treat the bearer token like a password. If a laptop is lost, a contractor leaves, or you accidentally pasted a token into a screenshot:

  1. Open Settings → AI Integration.
  2. Find the row, click Revoke. The token stops working immediately — no grace window like the HMAC shared secret has.
  3. Mint a fresh token and re-paste the snippet into your AI client.

Operator-scope tokens carry a built-in 90-day rotation nag: at day 75 the admin shows a banner reminding you to re-mint; at day 90 the token still works but new mutations increment a “stale token” audit counter. There is no hard expiry — your tooling won't suddenly break overnight — but the audit trail makes lingering tokens easy to spot during quarterly reviews.

What the AI can and can't see

Operator-MCP is scoped to your tenant. The AI cannot see other tenants' data, your billing details, or your team. It can read your search telemetry, your catalog index, your synonyms / pins / boosts, and your audit log; and (in the operator scope) it can mutate synonyms / pins / boosts and trigger re-indexing, re-training, and zero-results playbooks.

Every tool call writes a row to Settings → Audit → AI Integration with the originating token, the tool name, the request body, the result status, and a context log. Audit rows are retained 90 days.