FOR AGENTS

Run CPG Scheduler headless

Production planning is decision-work that rarely needs a screen. Point your own AI agent at our Model Context Protocol server with a token you mint, and it reads your live plan and acts on it — no GUI required. It is your agent, acting as you, on yourorganization’s data, narrowed to exactly the scopes you grant. This page is the complete reference: how it connects, the 50 tools it can discover, the scope model, and what you can build.

How it works

MCP is an open standard for handing an AI agent a set of tools it can call. Instead of you writing and maintaining a bespoke integration, our server publishes a typed list of tools; your agent connects, asks “what can you do?”, and calls what it needs. The transport is Streamable HTTP, and every request carries your token in an Authorization: Bearer header. Each tool is gated by a scope on that token, so the agent can reach exactly what you allowed and nothing else — discovery and authorization in one step.

Quickstart

1. Mint a scoped token. In your profile, create an agent access token and grant it only the scopes it needs — start read-only if you’re not sure. It’s shown once, stored only as a one-way hash, carries an expiry, and is revocable the instant you want it gone.
2. Connect your MCP client. Point it at the Streamable HTTP endpoint with an Authorization: Bearer <token> header. The endpoint is:
```
https://www.cpgscheduler.com/api/mcp/mcp
```
Most clients — desktop assistants, IDE agents, or your own code on an MCP SDK — take a small config block. Paste your token in place of the placeholder:
```
{
  "mcpServers": {
    "cpg-scheduler": {
      "type": "streamable-http",
      "url": "https://www.cpgscheduler.com/api/mcp/mcp",
      "headers": { "Authorization": "Bearer cpgsk_…" }
    }
  }
}
```
3. Let it work. On connect, your agent discovers the tools over MCP and calls them. Every call is gated by the matching scope on the token; your agent runs with exactly your permissions — never one scope more. Ask it a question, or give it a standing job.

Scopes

Tokens are least-privilege: a token does only what its scopes allow, and read and write are always separate. Grant read scopes for an observer; add the matching write scope only when you want the agent to act on that part of the plan. A token with runs:read can see the schedule but never change it; add runs:writeand it can schedule and adjust runs — but only runs. “Let an agent watch” and “let an agent act” stay independent decisions you make per token.

Scope	Grants
`runs:read`	Read runs and the production calendar.
`runs:write`	Schedule, update, split, complete, and acknowledge runs.
`skus:read`	Read SKUs, par levels, and velocity.
`skus:write`	Create and update SKUs.
`lines:read`	Read production lines and capacity.
`lines:write`	Create, update, and reorder lines.
`materials:read`	Read material masters, costs, and allergens.
`materials:write`	Create and update material masters.
`recipes:read`	Read BOM recipes and outputs.
`recipes:write`	Create and update BOM recipes.
`inventory:read`	Read material inventory, lots, and ledger entries.
`inventory:write`	Record stock movements and FEFO consumption.
`labels:read`	Read label templates, print history, and ZPL renders.
`labels:write`	Record server-rendered label print jobs.
`suppliers:read`	Read suppliers and supplier-material terms.
`suppliers:write`	Create/update suppliers and material terms.
`purchase-orders:read`	Read POs, suggested buys, and material demand.
`purchase-orders:write`	Create, issue, receive, and cancel POs.
`costing:read`	Read computed product COGS and allergen roll-ups.
`traceability:read`	Read upstream/downstream lot genealogy.
`uploads:read`	Read uploaded source-file audit records.
`alerts:read`	Read operational alerts.
`reports:read`	Read completed-run performance reports.

The tools

Read — observe the plan

26 read tools, each requiring the scope shown.

Production planning

list_production_runsruns:read
Every production run for your organization.
get_production_calendarruns:read
Calendar events, runs, lines, SKUs, and planning warnings.
list_skusskus:read
Every SKU with on-hand, par levels, and velocity.
list_production_lineslines:read
Production lines with capacity and constraints.
list_alertsalerts:read
Stockout risk, data staleness, due runs, pending approvals.
get_production_reportreports:read
Completed-run performance, optionally filtered by date / SKU / line.

Materials and recipes

list_materialsmaterials:read
Raw, packaging, intermediate, and finished materials.
get_materialmaterials:read
One material master record, including costing and allergen fields.
list_recipesrecipes:read
BOM recipes with output material and status summary.
get_reciperecipes:read
One recipe with input lines, co/by-products, and version details.

Inventory and traceability

list_inventoryinventory:read
Material inventory summaries with on-hand quantity and lot counts.
get_material_inventoryinventory:read
One material's lots, on-hand quantity, and stock ledger.
list_stock_ledgerinventory:read
Append-only stock movements for a material.
trace_lot_upstreamtraceability:read
Input-lot genealogy upstream from a material lot.
trace_lot_downstreamtraceability:read
Output-lot genealogy downstream from a material lot.

Labels

list_label_templateslabels:read
Label templates available for your organization.
get_label_templatelabels:read
One label template, including its document JSON.
render_labellabels:read
Render a single lot or SKU label as ZPL text only.
list_label_print_jobslabels:read
Recent label print-job audit records.

Procurement and costing

list_supplierssuppliers:read
Suppliers with material-link counts.
get_suppliersuppliers:read
One supplier with linked material terms.
list_purchase_orderspurchase-orders:read
Purchase orders with status and receipt progress.
get_purchase_orderpurchase-orders:read
One purchase order with line-level material receipt detail.
get_suggested_orderspurchase-orders:read
MRP netting: what to buy after inventory and open supply.
get_material_requirementspurchase-orders:read
Gross BOM demand for open runs before inventory netting.
get_product_costingcosting:read
COGS roll-up, cost-source detail, and rolled-up allergens.

Write — act on it

24 write tools. Each requires the matching *:write scope and runs through the very same code path the app uses when you click the button yourself — same validation, same organization scoping, same result.

Production planning

schedule_production_runruns:write
Schedule a new run for a SKU on a line.
update_production_runruns:write
Adjust a planned run — line, date, or batch count.
acknowledge_production_run_riskruns:write
Acknowledge a planning risk flagged on a run.
split_production_runruns:write
Split a planned run into two.
complete_production_runruns:write
Complete a run and reconcile BOM consumption/output lots.
create_skuskus:write
Add a SKU with its par levels and default line.
update_skuskus:write
Update a SKU's par levels, velocity, or default line.
create_production_linelines:write
Add a production line with its capacity.
update_production_linelines:write
Update a line's capacity or constraints.
reorder_production_lineslines:write
Reorder your active production lines.

Materials and recipes

create_materialmaterials:write
Add a material with replenishment, tracking, allergen, and cost fields.
update_materialmaterials:write
Update a material, including allergens and standard cost.
create_reciperecipes:write
Add a BOM recipe with input lines and co/by-products.
update_reciperecipes:write
Update a BOM recipe's batch, lines, outputs, and notes.

Inventory

record_stock_movementinventory:write
Record a receipt, consumption, or adjustment in the stock ledger.
consume_material_fefoinventory:write
Consume available material lots first-expired, first-out.

Labels

record_label_print_joblabels:write
Render server-derived ZPL and record the label print audit trail.

Procurement

create_suppliersuppliers:write
Add a supplier.
update_suppliersuppliers:write
Update a supplier.
upsert_supplier_materialsuppliers:write
Create or update supplier material price, MOQ, lead time, and preference.
create_purchase_orderpurchase-orders:write
Create a draft purchase order with material lines.
issue_purchase_orderpurchase-orders:write
Issue a draft purchase order.
receive_purchase_orderpurchase-orders:write
Receive PO lines and record material stock movements.
cancel_purchase_orderpurchase-orders:write
Cancel a draft or unreceived purchase order.

What you can build

A few patterns that fall out of the read + write toolset. Each lists the scopes it needs — grant only those.

A morning brief that schedules itself
Before standup, pull alerts and coverage, rank the exposed SKUs, schedule the runs that are clearly due, and leave a summary of what it did and what it left for your judgment.
Scopes runs:read · alerts:read · reports:read · runs:write
A coverage monitor that acts
On a schedule, check below-par coverage; for any high-priority SKU under its reorder point with open capacity on the right line, schedule the run and notify you. A message, not a fire.
Scopes runs:read · skus:read · runs:write
A procurement agent that prepares buys
Read gross demand, net it against inventory and open supply, choose preferred suppliers, create draft POs, and leave exceptions for materials with no supplier or production route.
Scopes purchase-orders:read · inventory:read · suppliers:read · purchase-orders:write
Print lot labels after a run
After a production run is complete, trace the output lot, render the operator-approved label as ZPL, and record the print job so the audit trail shows what was printed and by whom.
Scopes runs:read · traceability:read · labels:read · labels:write
A read-only watchdog
No write scopes at all — just an hourly read of alerts, inventory, traceability, and coverage that pings you when something crosses a line. The safest way to start: let it watch before it acts.
Scopes alerts:read · runs:read · inventory:read · traceability:read
A plain-language planning partner
Ask “can we fit a 5,000-unit rush of SKU-204 before Friday without blowing the changeover budget, material supply, or allergen constraints?” — answered against the live plan, BOM, costing, and inventory.
Scopes runs:read · lines:read · materials:read · recipes:read · costing:read

A morning, headless

At 6:00 your agent calls get_production_calendar and get_suggested_orders, spots a material gap behind a fast-mover, checks list_inventory and get_product_costing, then creates a draft PO or schedules the run that is safe to make — leaving you a note on what it did and why.

Observe → decide → act, before the first standup. Every call gated by the scopes on its token; nothing it couldn’t have done as you.

Good to know

Tokens are shown once. At creation you see the raw cpgsk_…token a single time; we store only a one-way hash. Copy it into your agent then — if it’s lost, revoke and mint a new one rather than hunting for it.
Expiry and rotation. Every token carries an expiry. For a standing job, rotate before it lapses; for a one-off, pick a short life. Mint a separate token per agent or task so you can revoke one without disturbing the others.
A missing scope fails closed.Call a tool the token doesn’t carry the scope for and it’s refused — no partial action, nothing silently widened. Grant the scope and retry; the agent never escalates on its own.
Org-isolated, acts as you.A token resolves to your user in your organization. Every read and write is scoped to that organization and carries your own permissions — an agent can never reach another tenant’s data or do anything you couldn’t do yourself.

Scoped, revocable, acts as you

Least privilege. A token carries only the scopes you grant. A token holding only reports:read pulls a variance report and nothing else; a token without runs:write can read your plan but never change it.

Reads and writes, never beyond you. Your agent can observe and act — pull the calendar, net material demand, create a draft PO, complete a run, or trace a lot. Every write is gated by its *:writescope and runs with exactly your permissions on your organization’s data. Your agent can never do anything you couldn’t do yourself in the app.

Yours alone. Tokens are one-way hashed at rest, shown once, expiring, and revocable instantly. This is first-partyaccess for an authenticated user’s own agent — org-isolated, not a public or general-purpose API, not a third-party developer platform, not an external sign-up. Nobody you didn’t authorize gets near your plan.

Mint a token in your profile Why headless & agentic