Assistant
Ask questions about your data in Claude, pull inventory and receiving reports, and build draft purchase orders from a confirmed replenishment order.
The assistant is a set of tools that Claude can use on your behalf. You connect Claude to the National Commerce server once, then talk to it in plain language. Claude picks the right tool, runs it against your data, and answers.
The assistant runs in the apps/mcp app as a Model Context Protocol (MCP)
server. It is separate from the portal screens, but it reads and writes the
same database.
Who can use it
The assistant is for National Commerce and OpsKings staff only. Your portal
login email must end in @nationalcommerce.com or @opskings.com. Brand users
sign in to the same portal, but cannot use the assistant, because its tools may
carry data brands must not see, such as vendor costs.
The server checks the login email on every request, not only when you connect. Anyone else gets "The MCP is available to National Commerce staff only." A connector a brand user already has stops working too, with nothing to revoke.
A brand user can still click Approve
The portal's Authorize Claude screen does not check the email. The refusal comes from the server right after, on Claude's first call to it.
Staff still only see the accounts they are assigned to in the portal.
Connect Claude
Add the server to Claude once as a custom connector. From then on every tool runs as you: you only see the accounts you have access to.
- In Claude (desktop or claude.ai), go to Customize → Connectors, click +, then Add custom connector.
- Paste
https://national-commerce-mcp.vercel.app/api/mcpand click Add. - Click Connect. Claude opens the portal login. Sign in with your portal email and the 6-digit code we email you (see Sign in to the portal), then click Approve on the Authorize Claude screen.
On a Claude Team or Enterprise plan, only a Claude Owner can add a custom connector, under Organization settings → Connectors. Once they have, each person finds it under Customize → Connectors and clicks Connect.
The address does not open in a browser
It only works inside Claude. Opening it in a browser shows these same connect steps instead of connecting anything.
What you can ask
Every tool except the two purchase-order tools only reads data.
| Tool | What it answers |
|---|---|
list_brands | Which accounts you can see. |
get_order_summary | Revenue, orders, and units shipped for a date range. |
get_low_stock_items | Inventory that needs restocking, by warehouse. Can be filtered to active or inactive SKUs. |
get_full_inventory_report | Every Base SKU at every warehouse for one account, including SKUs that don't need restocking. |
get_inbound_and_received_quantities | Units inbound and received per purchase order line for one account, optionally for a date range. |
get_top_skus | The best-selling SKUs for a date range. |
get_warehouse_stats | Units shipped per warehouse. |
get_shipping_costs | Shipping spend for a date range. |
get_daily_trend | Units shipped per day. |
search_skus | A product's Base SKU and Case SKU codes, from a name or partial code. Reads only. |
preview_draft_purchase_orders | What draft POs a confirmed order would become. Reads only. |
commit_draft_purchase_orders | Creates or updates those draft POs in the portal. Writes. |
Inventory and receiving reports
Three tools give reports and automations the full stock picture, so nobody has to export it from the portal by hand. All three only read.
Full inventory report
get_full_inventory_report returns every Base SKU at every warehouse for one
account. That includes SKUs above their reorder point and inactive SKUs, not
just the restock list.
Each row has the brand, SKU, product name, SKU status (Active or Inactive), warehouse, units on hand, units inbound, daily demand, days remaining, additional stock needed, and the rounded reorder quantity.
- Additional stock needed is 0 when the SKU is at or above its reorder point. The row is still returned.
- Days remaining is blank when daily demand is 0. A SKU with no demand is not out of stock, so it never reads as 0 days.
- Rounded reorder quantity is additional stock needed rounded up to the SKU's order multiple, the same as Amount To Reorder on the Replen Report.
- SKU status is Active only when the SKU is set to Active. Anything else reads as Inactive.
The account is required. You can also narrow to one warehouse or to active or inactive SKUs. For a company-wide pull, ask once per account.
Inbound and received quantities
get_inbound_and_received_quantities returns one row per purchase order line
for one account, in Base SKU units. Each row has the brand, Base SKU, product
name, warehouse, purchase order, its status, the SKU on the line, units per
case, quantity inbound, quantity received, date received, and expected arrival
date.
- Case lines are converted to units. A line of 5 cases with 12 units per case received shows 60 units received.
- Quantity inbound is ordered − received − rejected, on open (pending) purchase orders only. It is 0 on closed ones.
- Date received is the date the purchase order closed. On a purchase order that is still open but has units received, it is the line's last update date. There is no date per delivery.
- Left out: canceled purchase orders, lines with no Base or Case SKU link (non-inventory items), and closed lines with nothing received.
The date range is optional and covers whole days in UTC, both ends included. It filters received lines by date received. Open purchase order lines are always returned whatever the range, with their expected arrival date. Without a range you get every received line plus everything inbound.
Use the totals for a period
An open line returned in a date range can carry units received before the range started. The reply's totals only count units received inside the range, so ask Claude to report those rather than adding up rows.
A purchase order line on a -Case Base SKU that has no matching Case SKU can't
be converted to units. It is left out and counted in the reply, so the gap is
visible instead of silent.
Low stock, active only
get_low_stock_items takes an optional SKU status filter. Ask for active SKUs
only and inactive SKUs drop out of the restock list.
Same numbers as the Replen Report
The full report and the low-stock list read the same view as the Replen Report and correct it the same way:
- Inbound is recounted from pending purchase orders, with case lines multiplied by their units per case. Additional stock needed and the rounded reorder quantity are recomputed from it.
- Rows for
-CaseBase SKUs are hidden. These are cases that ended up in the Base SKUs table.
Inbound on these two tools is ordered − received, as on the Replen Report. The inbound and received tool also subtracts rejected units, so a line with rejections shows a smaller inbound figure there.
Large accounts
Every read pages past the database's 1,000-row limit, so no SKU, warehouse, or purchase order line is cut off. The full report and the inbound and received tool also send their rows back in pages of 200 by default, because a large account can have thousands of rows. Claude asks for the next page until it has them all. You don't need to do anything.
Build draft POs from a confirmed order
Every replenishment cycle the client sends back a confirmed order after their cuts. Instead of keying it into the portal line by line, hand it to the assistant and let it build the drafts for you.
How it works
- Paste the confirmed sheet into Claude and ask it to build the draft POs for the account. Claude reads the sheet, whatever shape it is in, and turns it into rows of warehouse, SKU, and quantity. The tool never parses the file itself.
- Claude resolves each line to a case. Replenishment is ordered in cases, so for every line it looks the product up with the search tool and takes the Case SKU code, whether the sheet gave a product name, a partial code, or the single-unit Base SKU code. A product with no Case SKU stays in single units.
- Claude previews the result. It calls the preview tool, which groups the rows one per warehouse, matches each SKU code exactly, and resolves the vendor from the account. Nothing is written yet. Any line still on a Base SKU that has a case equivalent is pointed out, with the case code and units per case, so you can switch it before anything is created.
- Check the preview. Claude shows you each warehouse group with its vendor, lines, and quantities, plus every row it could not match and why. Give it the correct SKU or warehouse for any flagged row.
- Confirm. Only after you say so does Claude call the commit tool. It creates one draft PO per warehouse with the matched lines. Rows that are still unmatched come back again in the reply; they are never dropped silently.
- Re-run to fold in fixes. If you resolve a flagged line afterwards, ask Claude to run it again. It passes the draft IDs from the first run, so the line is added to the existing draft and no duplicate PO is created.
- Review and submit in the portal. The drafts appear in the Purchase Orders list like any other draft. Open each one, check it, and click Submit to ShipHero yourself.
Replenishment cycles
When the account has one open replenishment cycle, the drafts are attached to it, so they show up on that cycle straight away.
A missing cycle never stops the drafts being created. If the account has no open cycle, or has more than one and the right one is not obvious, Claude creates the drafts unattached and tells you so. A deleted replenishment never counts as open. Attach them yourself from the cycle's Purchase Orders tab.
The assistant never pushes to ShipHero
Its job ends when the drafts exist. Submitting stays a button you click in the portal, so the human check stays in the loop.
Matching rules
- Account comes from the name you give; use
list_brandsfor the exact names. - Warehouse matches by name against the warehouses linked to that account.
- SKU matches by exact code, ignoring only letter case and surrounding spaces. Base SKU codes are tried first, then Case SKU codes. There is no fuzzy matching in the preview: a partial code comes back as unmatched. Looseness lives in the search tool instead, which is how Claude gets from a name or partial code to the exact code before previewing.
- Cases over units. A Base SKU is one sellable unit; a Case SKU is the box the warehouse receives, holding a fixed number of units. Replenishment lines should use the Case SKU. Claude resolves lines to cases through the search tool, and the preview flags any line still on a Base SKU that has a case equivalent. The switch is always shown to you and confirmed, never made silently, because 240 cases and 240 units are very different orders.
- Vendor is the account's vendor. If the account has more than one, the preview lists them and Claude asks which to use.
- Quantity must be a positive whole number. Two rows for the same warehouse and SKU are merged into one line.
- Price is always 0, the same as a draft built by hand.
What it writes
The drafts use the same records as the manual create form, so the PO list, the edit screen, and Submit to ShipHero all work on them unchanged:
- One row in
Inventory Replen Draft Purchase Orders per
warehouse, named
PO-<timestamp>, status Draft, vendor stored as the ShipHero vendor ID. - One row in the draft line items table per matched line, pointing at either the Base SKU or the Case SKU.
On a re-run against existing drafts, a SKU already on the draft has its quantity updated, a new SKU is added, and lines you removed from the sheet are left alone. A draft that has already been sent to ShipHero, or belongs to another account or warehouse, is refused and reported.
Write access
Every tool was read-only until the commit tool. Writes are switched on by one
server setting: MCP_WRITE_ENABLED=true in the environment of the MCP
deployment. Without it, the commit tool refuses and writes nothing. The
preview tool always works.
Who can write is decided the same way as who can read: you only ever see, and write to, the accounts you are assigned to in the portal.
Test it by hand
Use this checklist after a deploy, or whenever the tool instructions change.
- Connect Claude to the server. Confirm
list_brandsreturns your accounts. - With
MCP_WRITE_ENABLEDoff, paste a confirmed order that spans two warehouses and includes one SKU that does not exist. Ask Claude to build the drafts. It should show a preview with two groups and one flagged line, and the Purchase Orders list should show no new draft. - Ask Claude to commit anyway. It should refuse with a write-access message.
- Turn
MCP_WRITE_ENABLEDon, redeploy, and repeat the request. Confirm the preview. Two drafts should appear in the Purchase Orders list with the right lines and quantities, and the flagged line should be listed in the reply. - Give Claude the correct SKU and ask it to re-run. The line should land on the existing draft for its warehouse. There should still be exactly two drafts.
- Open each draft and check it against the sheet. Delete the test drafts from the list when you are done. Do not submit test drafts to ShipHero; a pushed PO is a real order and adds inbound quantity.
Test the reports by hand
Pick an account that has a SKU above its reorder point, an inactive SKU, a SKU with stock on hand and no demand, an open purchase order, and a closed purchase order received by the case.
- Ask Claude for the account's full inventory. SKUs above their reorder point show additional stock needed 0, the inactive SKU shows Inactive, and the SKU with no demand shows days remaining blank.
- Compare a few rows with the Replen Report for the same account. Inbound, additional stock needed, and amount to reorder should match.
- Ask for one warehouse, then active SKUs only. The report narrows each time.
- Ask for inbound and received quantities over a date range. On the closed case purchase order, units received should be cases received × units per case, dated by the close date.
- Check the open purchase order. It shows quantity inbound and its expected arrival date, and it comes back whatever the date range.
- Ask for low-stock items, active only. Inactive SKUs should drop out.