Add packaging quoting to your AI agent: MCP and the headless API

What your agent gets

The goal is narrow and useful: your agent takes something a user already has — a product spec, artwork, a die file, or a previous quote — and returns a real packaging quote instead of a vague guess. Under the hood that means PackOS reads the file into a structured spec, rebuilds the package structure, prices it across a quantity ladder, and returns a link the user can open. Your agent never has to model board grades or press setup; it calls one capability and gets a priced result. For the pipeline behind that, see how instant packaging quotes work.

There are two integration surfaces, and you pick based on how your agent is built. If it speaks the Model Context Protocol, the MCP server is the least code. If it is a plain script or a backend service, the headless API is four HTTP calls. Both authenticate with the same partner key and both credit qualified quotes to that key under the partner program.

Register a partner key

Registration is self-serve: one request returns a sandbox key you can build against immediately — no human in the loop, no setup call. You link a payout account later, only when there are earnings to cash out. Here is the registration call (this endpoint is in early access; check developers.html for the current base URL and status):

curl -X POST https://api.packos.ai/v1/partners/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Agent",
    "contact": "dev@acme.example",
    "origin": "https://acme.example"
  }'

# → 200 OK
# {
#   "partner_key": "pk_sandbox_9f2a...",
#   "mode": "sandbox",
#   "docs": "https://packos.ai/developers.html"
# }

Keep the partner_key where your agent can read it. It is public by design — it identifies the origin of a quote so attribution works, and it grants no access to uploads or account data. An agent can also find the register endpoint on its own by reading the discovery manifest, described in the .well-known/packos-partner.json spec.

The MCP path: point a server at PackOS

If your agent runtime supports the Model Context Protocol, the fastest integration is to register the PackOS MCP server. Once it is configured, the agent discovers a quoting tool by name and can call it like any other tool — no bespoke HTTP code. Add a server entry to your MCP client config (the server package and exact tool names are in early access; confirm on developers.html):

{
  "mcpServers": {
    "packos": {
      "command": "npx",
      "args": ["-y", "@packos/mcp-server"],
      "env": {
        "PACKOS_PARTNER_KEY": "pk_sandbox_9f2a..."
      }
    }
  }
}

With that in place the agent sees a tool such as get_packaging_quote. It accepts a file reference or a written spec and returns a structured result — the detected spec, the quantity ladder, and a quote URL for the user. Because the key travels in the server's environment rather than the model context, it stays out of the transcript. The MCP path is the right one for assistant-style agents and for listing in an MCP directory or a ChatGPT-app catalog.

The headless path: sign, PUT, commit, hand off

For a backend service or a script, call the API directly. The contract is four steps with no UI: ask PackOS to sign an upload, PUT the bytes to the returned storage URL, commit the upload so detection runs, then hand off the resulting quote link to the user. This is the same flow the embed performs; you are just doing it server-side. Here it is in JavaScript (endpoint shapes are the designed contract and in early access):

const KEY = process.env.PACKOS_PARTNER_KEY;
const API = "https://api.packos.ai/v1";

// 1. sign — ask for a one-time upload URL
const sign = await fetch(`${API}/uploads/sign`, {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-Partner-Key": KEY },
  body: JSON.stringify({ filename: "carton.pdf", content_type: "application/pdf" })
}).then(r => r.json());

// 2. PUT — send the file bytes straight to storage
await fetch(sign.upload_url, {
  method: "PUT",
  headers: { "Content-Type": "application/pdf" },
  body: fileBytes            // a Buffer / Blob of the spec file
});

// 3. commit — register the upload so detection + pricing run
const quote = await fetch(`${API}/quotes`, {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-Partner-Key": KEY },
  body: JSON.stringify({ upload_id: sign.upload_id })
}).then(r => r.json());

// 4. hand off — give the user the priced quote
console.log(quote.quote_url);   // https://quote.packos.ai/q/...

The upload URL is one-time and origin-checked. Your key rides in the X-Partner-Key header on the sign and commit calls; the raw PUT goes to storage and needs no key. Everything after the commit — detection, the cost model, the quantity ladder — happens on PackOS.

A worked example: spec in, quote out

Put the two paths together with a common agent task. A user tells your agent, "I need a quote for a 100 x 60 x 160 mm folding carton, SBS board, four-color." Your agent does not have to become a packaging estimator. It turns the spec into a small file or structured payload, calls the quoting capability, and returns the link. In Python, using a written spec rather than a file (spec-to-quote is in early access):

import os, requests

API = "https://api.packos.ai/v1"
KEY = os.environ["PACKOS_PARTNER_KEY"]

spec = {
    "structure": "folding_carton",
    "dimensions_mm": {"l": 100, "w": 60, "h": 160},
    "substrate": "SBS",
    "colors": 4
}

r = requests.post(
    f"{API}/quotes",
    headers={"X-Partner-Key": KEY},
    json={"spec": spec},
)
r.raise_for_status()
data = r.json()

print("Quote:", data["quote_url"])
print("Ladder:", data["quantity_ladder"])   # unit prices across order sizes

The agent hands the user quote_url and can read the quantity_ladder back into the conversation. For a fully custom structure or an ambiguous material, PackOS returns the assumptions it made and routes the edge cases to a person instead of a confident wrong number — the same honesty backstop the human product uses. If you would rather your agent build a page a user lands on, see building a packaging quote page with an agent.

The trust boundary: what stays on PackOS

The security story is deliberately simple: the embed and your agent are thin clients. They collect the file and carry a public partner key, and that is all. The upload target, the AI detection models, the cost model, and the attribution ledger live on PackOS. Nothing sensitive sits in your agent, in the browser, or in the model transcript, which is why the partner key is safe to ship in client code.

That boundary is what lets an agent run end to end on its own: register a key, embed the quote flow, and earn on the qualified quotes it drives — all self-serve, no gatekeeper. When there are earnings to withdraw, they pay out to a connected account you link at cash-out — fiat or a USDC wallet, your choice. How that works end to end is covered in how an AI agent earns commission with PackOS.

What is live, and what is early access

To be straight about status: Quick Quote is live for labels, flexible packaging, and folding cartons, and you can run a real file through it today. The partner program — key registration, the MCP server, the headless contract described here, and commission attribution — is in early access. Endpoint names and payloads above are the designed contract; treat developers.html as the source of truth for what has shipped. Payouts are not live yet, so there are no earnings to promise; when they open, the commission model (paid on real, qualified quotes — quality, not bot traffic — plus rev-share on a resulting order) and the exact rates are published to partners at signup.

If you want to start, register a sandbox key, wire the MCP server or the four headless calls, and run a spec through it. Join the early partner list so your key is attributed the moment the program opens.