Account & alerts
AI assistants (MCP)
Connect Cursor, Claude, ChatGPT, or another MCP client to your store so it can explain rules, simulate orders, diagnose shipments and price-test carts — with a personal token that can never do more than you can.
Intro
AI assistants lets an assistant read and reason about your store over MCP (Model Context Protocol): explain your automation rules, conditions and filters, run a described or real order through the real engines, work out why a shipment was or was not split or tagged, and price a cart against the checkout shipping rates. It uses the same engines as the Automation Rules Tester, the Rate Tester and Diagnose on an order.
There are two ways to use it:
- In-app assistant (Sidekick) — when your ShipManta instance has it enabled, a sparkles button at the bottom right opens a right-hand panel. No token. It uses your signed-in session and the same tools as Cursor, limited to what you can do on the active store. The empty state shows a core setup checklist (order import → warehouse → carrier → labels → shipments → conditions → automation → merge) with no AI cost. Open on Import orders from Shopify launches the order-import setup popup (which orders to pull in); other steps go to their settings pages. Free-form diagnose / “why” questions use the model. Writes from chat come back as a Confirm / Apply card. Apps stay on the Apps hub — not in this checklist.
- External clients (tokens) — open the user menu → Settings → AI assistants. Create a personal token for Cursor, Claude, or another MCP client. Each token is bound to the active store and limited to that person's own permissions.
Purpose
- Ask "why didn't order #152211 get the
-SDCtag?" and get the rule-by-rule answer - Simulate a rule you are about to build against a real order before you create it
- Get setup help (warehouse, carrier, which apps to turn on) from the in-app panel without leaving the page
- Let an assistant read a shipping-rate profile back to you in plain English
- Give a developer or consultant scoped, revocable access without a ShipManta login
What the assistant can do
Access is granted per module; the assistant only sees tools from the modules on the token, and only those your own permissions allow.
| Module | Tools |
|---|---|
| Core | Who am I, store overview, store settings, per-location settings (list, and change with your confirmation) |
| Automation rules | List and explain rules, conditions and tags; dry-run described or real orders (optionally only a draft group); diagnose why an order did or did not trigger rules |
| Import & shipment filters | List and explain store and shipment filters; dry-run them against a real order |
| Orders & shipments | Search and inspect orders and shipments; diagnose why no shipment exists; read and (with changes enabled) edit the merge rules and Merge Settings including the Merge Conflict Tags; list and cancel shipments left with no items; re-sync a fulfilled order's shipments with the store |
| Shipping Rates (checkout) | Read, explain and price-test profiles — zones, groups, tiers, combination and fold rules, triggers |
| Delivery Calendar (checkout dates) | Calendars, rules, exceptions and limit rules; replay a cart to see which dates a buyer gets; diagnose where an order's delivery date came from; capacity per day |
| Operations (alerts, routines, hooks, printing, integration health) | The alerts inbox by level, code or subject — and, with changes enabled, acknowledge, snooze or resolve them; routines and their runs step by step; hooks — list them, read a run, create one as a draft, test it on a shipment, and switch it on (activating a live hook comes back as a preview); document templates — list them, read the HTML, and with changes enabled save an edit (any field the template editor has; the change comes back as a preview); document templates — including Mustache tags ({{ }}, {{# }}, {{^ }}, {{> shopped_tag }}, message partials) and Rate Shopper shopped rates on the printout; document messages (Pro / Enterprise) — list them, dry-run them on a real shipment, create one as a draft, edit or switch it on (a live message comes back as a preview) and delete it (preview first); the print history of a shipment; a one-call health check of Shopify webhooks, the checkout rate callback, the fulfillment provider and the weather feed; the log of recent checkout rate requests |
| Carrier Claims | Late FedEx and UPS money-back claims: list and explain why a claim is open or skipped. With changes enabled, scan recent labels and mark filed / recovered / skipped / denied — each write comes back as a preview. ShipManta never files with the carrier |
| Delivery Status | Purchased labels and delivery progress (Pro+): list / get cached track status, see which carriers have tracking on. With changes enabled, sync a batch, refresh one label, or turn tracking on/off per carrier — each write comes back as a preview. Separate from Carrier Claims |
| Packing Materials | Containers and supplies catalog; usage report and packer materials; packing on one shipment label. With changes enabled, create / edit / delete catalog entries — each write comes back as a preview. Costs on past labels stay snapshotted |
Whether an assistant may change anything depends on how your ShipManta is configured:
- Read-only — the page shows Read-only for now: assistants inspect, explain, simulate and diagnose, but no tool creates, edits, deletes or activates anything. Rules, filters, shipments and shipping rates are only changed in ShipManta itself.
- Changes enabled — the modules also carry the tools you have in that area: tag, split, merge, hold and re-run automation on shipments; create and edit rules, conditions, tags and filters; edit shipping-rate profiles. Anything that touches live data comes back to the assistant as a preview you must confirm, and new rules, conditions and filters are created as inactive drafts so you can dry-run them before switching them on.
Every call is logged under your account either way.
The most useful first prompt: "Read the ShipManta guide, then explain my automation rules and simulate an order that mixes two product types." Ask the assistant to simulate a proposed rule against a real order number before you create it — it runs the same engine the Automation Tester does.
Create a token
- Click New token.
- Name it after where you will use it (Cursor on laptop).
- Tick the Modules the assistant may access (all are pre-ticked).
- Optionally set Expires in (days) — 1 to 730; leave empty for no expiry. You can revoke at any time.
- Create token. Copy it now — it is not shown again.
Connect your assistant
The Token created step offers ready-made connections:
| Client | How |
|---|---|
| Cursor | Add to Cursor opens Cursor with the server (storesboost-{store}) and token pre-filled — confirm and you are done. If nothing opens, Copy mcp.json and paste it into ~/.cursor/mcp.json |
| Claude Code | Copy the single claude mcp add --transport http --scope user … command into a terminal (--scope user makes it available in every project) |
| Claude Desktop | Copy the config block into Settings → Developer → Edit Config (claude_desktop_config.json), then fully quit and reopen Claude. It bridges through mcp-remote, so Node.js must be installed |
Other MCP clients: use the Server URL shown on the page with the token as a Bearer Authorization header. Each store gets its own server name, so a multi-store user does not overwrite one connection with another. ChatGPT and Claude's custom connectors need OAuth sign-in, which is not available yet.
Manage tokens
Your tokens for {store} lists each token with its modules, when it was created, last used and expires. Revoke cuts access immediately — any assistant using that token stops working on its next call. Tokens honour exactly the expiry you set; a token without an expiry keeps working until you revoke it.
In-app vs tokens
| In-app (top bar) | Cursor / Claude tokens | |
|---|---|---|
| Where | Bottom-right sparkles → right panel | Settings → AI assistants |
| Auth | Your login session | Personal Bearer token |
| Store | Always the active store | Bound when the token was created |
| Modules | All modules your permissions allow | Only modules you tick on the token |
| Writes | Same global setting; Apply in the panel | Same; confirm in the external chat |
If you do not see the sparkles button, the in-app assistant is turned off for your instance — use a token instead, or ask your ShipManta admin.
Troubleshooting
- No sparkles button at the bottom right → the in-app assistant is disabled on this instance (
ASSISTANT_ENABLED). Use a Cursor/Claude token, or ask your admin to enable it. - In-app says chat needs an AI key → the panel is on but the server has no model key yet; tools still work via external tokens.
- The assistant says a tool is missing → the module is not on the token, or your own role lacks the matching permission (for example View automation rules). Create a new token or ask an admin to adjust your role.
- "Not authenticated" after it worked before → the token expired or was revoked; create a new one and update the client.
- It sees the wrong store → tokens are bound to the store that was active when you created them. Switch stores and create another token; each store gets its own server entry. The in-app panel always follows the store switcher.
- A change was not applied → in read-only mode nothing is written; with changes enabled, every live change needs your confirmation (Apply in the panel, or confirm in the external chat), and rules or filters are created as drafts you still have to activate.
Related
- Getting started — first-time checklist the in-app assistant can walk you through
- Automation rules — the tester the assistant reuses
- Store Filters & Shipment Filters — filter dry runs
- Shipping Rates · Delivery Calendar
- Roles & permissions — what bounds every token