Reference

MCP server

A stdio Model Context Protocol server that gives an assistant the solver and both catalogs, over the public REST API.

An HTTP client of /api/v1, with no privilege of its own.

Install

1 — build it

pnpm --filter @cartonpackpro/mcp-server build
echo "$PWD/packages/mcp-server/dist/index.js"   # the path for "args"

2 — claude_desktop_config.json, or .mcp.json at a repository root

{
  "mcpServers": {
    "carton-pack-pro": {
      "command": "node",
      "args": ["/absolute/path/to/packages/mcp-server/dist/index.js"],
      "env": {
        "CARTON_PACK_PRO_BASE_URL": "https://carton.example.com",
        "CARTON_PACK_PRO_API_KEY": "cpp_live_7Qk2nR4vT8xW1yZ3aB5cD6eF9gH0jK2mN4pQ6rS8"
      }
    }
  }
}

Key	Value
`args`	One absolute path to the built `dist/index.js`. A relative path cannot resolve — the client chooses its own working directory.
`CARTON_PACK_PRO_BASE_URL`	Your instance origin, no trailing path; `/api/v1` is appended. Defaults to `http://localhost:3000`.
`CARTON_PACK_PRO_API_KEY`	Required. A key from `/api-keys`, ideally named for the machine it runs on. Revoking it is the whole of turning the server off.
`CARTON_PACK_PRO_TIMEOUT_MS`	Optional. 1000 to 300000, default 30000.

Tools

Tool	Scope	Returns
`pack_order`	`write`	Solves an order. Cartons, contents, steps, billable weight, 3D link. Files a pack job unless save is false.
`compare_cartons`	`write`	Same order against two or more carton sets. Count, billable weight, cost and fill side by side. Files nothing by default.
`list_cartons`	`read`	The packaging catalog: interior dimensions, usable volume after padding, on hand, unit cost.
`get_carton_stock`	`read`	With no argument, every carton at or below its reorder point, worst shortfall first. With a SKU, that one.
`list_items`	`read`	The product catalog, paginated, with dimensions and handling constraints.
`search_items`	`read`	Finds a SKU by code, name or category. What resolves an order written in words.
`list_pack_jobs`	`read`	History, newest first. Reference, order number, cartons, units, billable weight.
`get_pack_job`	`read`	One stored plan in full. Takes our reference, the job id, or your order number.
`create_carton`	`write`	Adds a packaging type. Counts against the carton-type ceiling.
`create_item`	`write`	Adds a SKU with its shipping footprint. Counts against the item ceiling.
`get_usage`	`read`	Plan, consumption this month, and every ceiling.

Every tool is scoped to the organization that owns the key, and every plan ceiling that applies to the API applies here: a solve through pack_order spends one pack job. A read-only key answers every question but cannot solve or write.

Resources and prompts

URI	Contents
`cartonpackpro://cartons`	Every active carton, as JSON.
`cartonpackpro://items`	Every active item, as JSON.
`cartonpackpro://openapi`	The live OpenAPI document, for the routes these tools do not wrap.
`pack-this-order`	Prompt. Turns a pasted order — email, pick list, spreadsheet row — into a plan with packing steps.
`which-carton`	Prompt. Picks a carton for a SKU list, then compares the realistic alternatives.

Troubleshooting

Status	code	Cause
no tools	args	The path is relative, or `dist/index.js` does not exist yet. Build, fix the path, restart the client.
exits at launch	ConfigError	`CARTON_PACK_PRO_API_KEY` is unset, or the base URL is not an absolute http(s) URL. The reason is on stderr.
401	unauthorized	Key revoked, mistyped, or from another instance.
403	forbidden	Read-only key. Scopes are fixed at creation, so make a new key.
402	plan_limit_reached	A ceiling. `get_usage` names which; the monthly one resets on the first of the UTC month.
429	rate_limited	Per-key bucket. The message says how long to wait.