Reference
MCP server
Pack orders and look up or add cartons and items from Claude or any MCP client.
One API key is the whole grant: its scopes, its organization and its plan limits apply unchanged. Revoking the key turns the server off.
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 | The absolute path to the built dist/index.js. A relative path fails because the client picks its own working directory. |
CARTON_PACK_PRO_BASE_URL | The address you sign in at, with no path; /api/v1 is added. Defaults to http://localhost:3000. |
CARTON_PACK_PRO_API_KEY | Required. A key from /api-keys, ideally named for the machine it runs on. To turn the server off, revoke the key. |
CARTON_PACK_PRO_TIMEOUT_MS | Optional. 1000 to 300000, default 30000. |
Tools
| Tool | Scope | Returns |
|---|---|---|
pack_order | write | Cartonizes an order. Returns cartons, contents, packing steps, billable weight and a 3D link. A line can set nestIncrement and maxNestQuantity for units that nest, like cups. Saves the plan as a pack job unless save is false. A saved job with a shipTo gets live rates through your ShipStation API key. LOWEST_RATE keeps the plan with the lowest carton cost plus live rate. If shipTo, save true or a ShipStation API key is missing, it returns the MIN_COST plan and a warning. |
compare_cartons | write | Packs one order against two to six carton sets and shows carton count, billable weight, cost and fill side by side. Lines take nestIncrement and maxNestQuantity as on pack_order. Saves nothing unless save is true. |
list_cartons | read | The packaging catalog: interior dimensions, usable volume after padding, unit cost. |
list_items | read | The product catalog, paginated, with dimensions and handling constraints. |
search_items | read | Finds a SKU by code or name. Use it when an order names products instead of SKUs. |
list_pack_jobs | read | Past pack jobs, newest first, with reference, order number, cartons, units and 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 toward your plan’s carton-type limit. |
create_item | write | Adds a SKU with its dimensions and weight. For an item that nests, like cups, it also takes nestIncrement and maxNestQuantity. Counts toward your plan’s item limit. |
get_usage | read | Your plan, this month’s usage and every plan limit. |
Every tool sees only the key’s organization. API plan limits apply here too: pack_order uses one pack job unless save is false. A read-only key can use only the read tools.
Resources and prompts
| URI | Contents |
|---|---|
cartonpackpro://cartons | Every active carton, as JSON, up to 1,200. Past that, truncated is true. |
cartonpackpro://items | Every active item, as JSON, up to 1,200. Past that, truncated is true. |
cartonpackpro://openapi | The live OpenAPI document, for API routes no tool covers. |
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 and compares billable weight and carton cost against two or three others that fit. |
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 made on a different site than the base URL. |
| 403 | forbidden | Read-only key. Scopes are fixed at creation, so make a new key. |
| 402 | plan_limit_reached | A plan limit is reached, or your plan has no MCP server (Business and Enterprise only). The message says which. Monthly pack jobs reset on the 1st (UTC). |
| 429 | rate_limited | Too many requests from this key. The message says how long to wait. |