@easypod/mcp

MCP server for the EasyPod / CustomHub Partner API. Lets AI coding agents (Claude Code, Cursor, …) browse the print-on-demand catalog, quote exact costs, place orders, and track fulfillment — with safety rails on the money path.

Setup

1. Create an API key in the dealer portal: Settings → API Keys, scopes products_r + orders_r + orders_w (orders_r powers the quote-based cost gate, balance checks, and order tracking — don't skip it).
2. Add to your MCP config (~/.claude/mcp.json, ~/.cursor/mcp.json, …):

{
  "mcpServers": {
    "easypod": {
      "command": "npx",
      "args": ["-y", "@easypod/mcp"],
      "env": {
        "EASYPOD_API_KEY": "ek_live_...",
        "EASYPOD_SECRET_KEY": "esk_live_...",
        "EASYPOD_MAX_ORDER_COST": "100"   // optional; per-order cap, default 100, "off" to disable
      }
    }
  }
}

Pre-publish / local development:

{ "command": "node", "args": ["/path/to/packages/easypod-mcp/dist/cli.js"], "env": { ... } }

Other env: EASYPOD_API_URL, EASYPOD_IDENTITY_URL (override for other CustomHub-powered tenants).

Tools

| Tool | What it does | |---|---| | easypod_list_models | Browse the catalog (models + "from" pricing) | | easypod_get_model | Variations (orderable SKUs, pricing, default print sizes) + placements (codes + max print dims + print prices) | | easypod_quote_order | Exact cost of a would-be order — no order created | | easypod_create_order | Submit a real order (requires confirm: true; runs the cost gate) | | easypod_get_order | One order: status, shipments, tracking, locked cost, events[] audit trail | | easypod_list_orders | Paged summaries; filter by since/status/externalOrderId | | easypod_get_balance | Wallet snapshot: balance, credit limit, headroom | | easypod_cancel_order | Retract an order while it's still pending approval (never charged) |

Safety model

Multiple layers between an agent and spent money:

1. Admin-approval gate (server-side). Every order lands in ApprovalPending. The wallet is only debited when a human admin in the tenant dashboard approves — at exactly the cost quoted at submit (locked). Until then easypod_cancel_order retracts it free.
2. Quote-first workflow. Tool descriptions and server instructions require quoting and showing the user the total before creating.
3. confirm: true required. easypod_create_order refuses without it; it must reflect explicit user approval.
4. Cost gate. The server pre-quotes each create and refuses when the total exceeds EASYPOD_MAX_ORDER_COST (default 100, dealer currency; off disables). Fails closed if the key can't quote (missing orders_r).
5. Least-privilege keys. Scope the key to exactly products_r + orders_r + orders_w; revoke any time in Settings → API Keys.

Notes

• externalOrderId doubles as the idempotency key (per dealer, 90-day memory). Failures are cached against it — retry-after-fix needs a new id (-r1, -r2, …). On ORDER_CREATE_IN_PROGRESS, don't switch ids; look the id up via easypod_list_orders.
• No webhooks yet — poll easypod_list_orders / easypod_get_order.
• Designs: HTTPS PNG/JPEG only, ≤ 100 MB each, ≤ 50 per order. Use placement codes (width1..width5, gang_sheet), never display labels. Explicit widthInches/heightInches are required on quote and create (defaults are in easypod_get_model variations[].defaultPrintSizes).
• FORBIDDEN can mean the key lacks a scope or the dealer account has no shop yet.
• Rate limit: 60 requests/min per credential.