MCP CONNECTION
Connect Insights MCP
Let your AI assistant read Boxme Insights operational data directly — warehouse backlog, delivery performance, handover risk and returns — without opening a dashboard.
OVERVIEW
What MCP is, and what it is not
MCP (Model Context Protocol) is how an AI assistant — Claude, for example — connects to a system in order to read data. Once connected you ask in plain language (“how many orders are still unshipped today?”) and the assistant calls the matching report and answers.
This connection is read-only. An MCP session cannot create, change or delete anything: no dashboard edits, no new data sources, no sharing, no account changes. That limit is enforced on the server; it is not an option.
SETUP
Connect in four steps
Sign in to Insights first, in the same browser.
Without an active session the authorisation page sends you to the login screen and stops there — the authorisation URL stays in the address bar but does not continue on its own. This is the single most common reason a connection fails.
-
Sign in to Insights
Sign in with your seller account and leave the tab open.
-
Add the connector in Claude
Go to Settings → Connectors → Add custom connector and paste the MCP server address above. No Client ID is needed — registration is automatic.
-
Authorise
Claude sends you back to Insights to confirm. Because you signed in at step 1, the consent screen appears straight away. Press Allow.
Check the application name on the consent screen before pressing — that name is declared by the application itself.
-
Try a question
For example: “List the Insights reports I can run”, then “Over the last 5 days, how many orders are still backlogged at the warehouse, by carrier?”
CATALOGUE
What the assistant can read
Exactly what you see on the three screens — Backlog, Delivery and Omisell Reconciliation — and no more. The numbers come from two different systems, and the prefix of the report code is what tells them apart.
Boxme OMS
BM-*Backlog and delivery on the Boxme warehouse side — the Backlog and Delivery screens.
| Code | What it covers | Default (days) | Max (days) |
|---|---|---|---|
| BM-BACKLOG-SUMMARY | Orders still open at the warehouse: total, orders with no SLA, and splits by sales channel, order type, prepack, carrier and SLA bucket, with a daily series. | 5 | 90 |
| BM-BACKLOG-ORDERS | The line-by-line list of open orders: warehouse, carrier, tracking number, order code, creation time and both SLA marks. | 5 | 90 |
| BM-BACKLOG-FILTERS | The filter values available to you: warehouse, carrier, sales channel, status, order type, SLA bucket. | 5 | 90 |
| BM-DELIVERY-OPS-OVERVIEW | Last-mile delivery: KPIs, order age, delivery attempts, failure and return reasons, split by carrier, warehouse, service, status and region. | 14 | 90 |
| BM-DELIVERY-OPS-ORDERS | The line-by-line list of shipments behind the report above. | 14 | 90 |
Omisell
OM-*Reconciliation between Omisell and OMS — the Omisell Reconciliation screen. Note: OM-BACKLOG-SUMMARY counts differently from BM-BACKLOG-SUMMARY. One measures the Omisell → OMS handover step, the other measures what is still open at the warehouse.
| Code | What it covers | Default (days) | Max (days) |
|---|---|---|---|
| OM-BACKLOG-SUMMARY | Orders waiting to be pushed to OMS against orders that already have a 3PF shipment, per warehouse. | 30 | 90 |
| OM-BACKLOG-FILTERS | Filter values for the OM group: store, order status, carrier. | 30 | 90 |
| OM-HANDOVER-RISK-SUMMARY | Handover risk: orders cancelled after a shipment was created, and orders whose status differs between Omisell and OMS, totalled per warehouse. | 7 | 14 |
| OM-HANDOVER-RISK-ORDERS | The line-by-line list of orders at handover risk. Pick one type: cancelled or status_mismatch. | 7 | 14 |
| OM-RETURN-RISK-SUMMARY | Risk when taking returns back into the warehouse, totalled by sales channel and warehouse. | 30 | 90 |
| OM-RETURN-RISK-ORDERS | The line-by-line list of orders at risk on return intake. | 30 | 90 |
DATA SCOPE
The boundary, and who decides it
Scope is imposed by the server, not by the AI assistant and not by your question. The assistant does not send a shop code, and if it did the server would override it. The same report gives two different results to two different accounts.
Can read
- Data rows for the shops you are entitled to. With several shops the default is the total of all shops in the selected market.
- Narrowed filters: the list of warehouses, carriers and sales channels holds only the values inside your scope.
- All 11 reports above, exactly matching what the three portal screens display.
Cannot read
- Another shop's data — even when asked for directly by shop code.
- Per-seller breakdown reports — they name other businesses, so they are not open to sellers.
- Ad-hoc tables, hand-written SQL, or anything outside the catalogue above.
- Any write action. This connection cannot change anything.
READING THE NUMBERS
Three things to know before trusting a number
There is no “last updated” mark. Every report returns data_as_of: unknown, because the source system does not publish its refresh time. Do not present the results as real-time figures.
The time window is capped, and it is narrowed with notice. Ask for more than the maximum and the result shrinks, and the answer says so. For the OM-* group specifically, orders that started more than 90 days ago fall outside the window — a window sitting entirely in the distant past is narrowed rather than answered with wrong numbers.
Money is not converted. Monetary values keep each store's own currency, so a total may be adding up several currencies.
The window filters on when the order was created at the store, not on when the order was still open. For backlog reports, widening the window usually does not change the total.
TROUBLESHOOTING
Three common errors
Login finishes but the page just sits on the home screen
The authorisation flow does not resume by itself after login. Fix: open insights.boxme.asia, sign in, then add the connector again from the start in that same browser.
An invalid Client ID error
Invalid client_id parameter value
This message is usually not about the Client ID but about your account not yet having Insights access. Send your account email to your Boxme contact so the permissions can be checked.
The assistant says it has no permission to read a table
You do not have permission to access this table
This is not a misconfiguration on your side. Send the exact question you asked to your Boxme contact — the message points to a data table not yet opened to seller scope, and it needs fixing on the system side.
Boxme Insights · MCP connection guide for sellers. The report catalogue and window limits on this page are read from the running system (insights_seller 0.0.27).