National Commerce Docs
Feature guides

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.

  1. In Claude (desktop or claude.ai), go to Customize → Connectors, click +, then Add custom connector.
  2. Paste https://national-commerce-mcp.vercel.app/api/mcp and click Add.
  3. 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.

ToolWhat it answers
list_brandsWhich accounts you can see.
get_order_summaryRevenue, orders, and units shipped for a date range.
get_low_stock_itemsInventory that needs restocking, by warehouse. Can be filtered to active or inactive SKUs.
get_full_inventory_reportEvery Base SKU at every warehouse for one account, including SKUs that don't need restocking.
get_inbound_and_received_quantitiesUnits inbound and received per purchase order line for one account, optionally for a date range.
get_top_skusThe best-selling SKUs for a date range.
get_warehouse_statsUnits shipped per warehouse.
get_shipping_costsShipping spend for a date range.
get_daily_trendUnits shipped per day.
search_skusA product's Base SKU and Case SKU codes, from a name or partial code. Reads only.
preview_draft_purchase_ordersWhat draft POs a confirmed order would become. Reads only.
commit_draft_purchase_ordersCreates 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 -Case Base 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

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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_brands for 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.

  1. Connect Claude to the server. Confirm list_brands returns your accounts.
  2. With MCP_WRITE_ENABLED off, 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.
  3. Ask Claude to commit anyway. It should refuse with a write-access message.
  4. Turn MCP_WRITE_ENABLED on, 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.
  5. 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.
  6. 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.

  1. 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.
  2. Compare a few rows with the Replen Report for the same account. Inbound, additional stock needed, and amount to reorder should match.
  3. Ask for one warehouse, then active SKUs only. The report narrows each time.
  4. 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.
  5. Check the open purchase order. It shows quantity inbound and its expected arrival date, and it comes back whatever the date range.
  6. Ask for low-stock items, active only. Inactive SKUs should drop out.

On this page