Model Context Protocol (MCP) & Agent Skills
PrintPrice OS exposes its industrial print-estimation, spine geometry, 3D pallet cubing, imposition, and 6-axis PDF preflight engines through the official Model Context Protocol (MCP) server (@ppos/mcp-server) and a deterministic Agent Skill (printprice-mcp-orchestrator).
Connect any MCP-compatible AI client—such as Claude Desktop, Cursor, Antigravity, or custom agent runtimes—directly to https://control.printprice.pro without writing boilerplate API glue.
- GitHub Release: github.com/PrintPriceOS/ppos-mcp-server#v1.1.0
- Direct stdio execution:
npx -y github:PrintPriceOS/ppos-mcp-server#v1.1.0 - Remote Streamable HTTP:
https://mcp.printprice.pro/mcp - npm Package:
@ppos/mcp-server(v1.1.0+) - Built-in Agent Skill:
.agents/skills/printprice-mcp-orchestrator/SKILL.md
1. Prerequisites & Authentication
Obtain your credentials from the PrintPricePro Developer Portal (https://printprice.pro/developers):
| Environment Variable | Required | Default | Description |
|---|---|---|---|
PPOS_BASE_URL | No | https://control.printprice.pro | Target PrintPrice OS Control Plane endpoint. |
PPOS_API_KEY | Yes | — | Developer API Key (pp_test_<32hex> for Sandbox or pp_live_<32hex> for Production). |
PPOS_JWT_TOKEN | Conditional | — | Operator/Admin Bearer JWT (<YOUR_OPERATOR_JWT_TOKEN>). Required for admin-scoped endpoints such as /api/v1/spine/calculate. |
PPOS_MARKETPLACE_TOKEN | Conditional | — | Machine-to-machine intake token for creating or updating Marketplace orders. |
PPOS_HTTP_TIMEOUT_MS | No | 15000 | Upstream HTTP timeout in milliseconds (matches the 15s BPE guard). |
Never hardcode API keys or JWTs in configuration files committed to version control. @ppos/mcp-server automatically strips client-supplied tenantId / x-tenant-id fields so the Control Plane resolves tenant ownership strictly from your authenticated credential.
2. Quickstart: Local Installation (npx / stdio)
For desktop AI assistants, run @ppos/mcp-server over standard input/output (stdio) via npx, or build directly from source.
- Claude Desktop
- Cursor / Antigravity
- Build from Source
Add the printpricepro entry to your claude_desktop_config.json:
{
"mcpServers": {
"printpricepro": {
"command": "npx",
"args": ["-y", "github:PrintPriceOS/ppos-mcp-server#v1.1.0"],
"env": {
"PPOS_BASE_URL": "https://control.printprice.pro",
"PPOS_API_KEY": "pp_test_your_api_key_here",
"PPOS_JWT_TOKEN": "<YOUR_OPERATOR_JWT_TOKEN>"
}
}
}
}
Add the server configuration to your workspace .cursor/mcp.json or global mcp_config.json:
{
"mcpServers": {
"printpricepro": {
"command": "npx",
"args": ["-y", "github:PrintPriceOS/ppos-mcp-server#v1.1.0"],
"env": {
"PPOS_BASE_URL": "https://control.printprice.pro",
"PPOS_API_KEY": "pp_test_your_api_key_here"
}
}
}
}
Clone and compile the MCP server locally:
git clone https://github.com/PrintPriceOS/ppos-mcp-server.git
cd ppos-mcp-server
npm install
npm run build
Then point "command": "node" and "args": ["/absolute/path/to/ppos-mcp-server/dist/index.js"] in your client configuration.
3. Remote Deployment (Streamable HTTP)
For cloud agent orchestrators, web backends, or shared internal infrastructure, @ppos/mcp-server supports the Streamable HTTP MCP transport (MCP_TRANSPORT=http).
Server Environment Variables
MCP_TRANSPORT=http
MCP_HOST=127.0.0.1
MCP_PORT=8090
PPOS_BASE_URL=https://control.printprice.pro
PPOS_API_KEY=pp_live_your_production_key
PPOS_JWT_TOKEN=<YOUR_OPERATOR_JWT_TOKEN>
Launching the Remote Server
MCP_TRANSPORT=http MCP_HOST=0.0.0.0 MCP_PORT=8090 npx -y github:PrintPriceOS/ppos-mcp-server#v1.1.0
Exposed HTTP Endpoints
| Method & Path | Purpose |
|---|---|
POST /mcp | JSON-RPC Streamable HTTP endpoint for MCP initialize, tools/list, tools/call, and resources/read requests. |
GET /mcp | Server-Sent Events (SSE) stream for active mcp-session-id sessions. |
DELETE /mcp | Terminates an active MCP session cleanly. |
GET /health | Liveness probe returning 200 OK with {"status":"ok","server":"@ppos/mcp-server","version":"1.1.0"}. |
Connecting a Remote MCP Client
{
"mcpServers": {
"printpricepro-remote": {
"url": "https://mcp.printprice.pro/mcp"
}
}
}
4. Available MCP Tools & Resources
Tools (10)
| Tool Name | Domain | Purpose |
|---|---|---|
ppos_search_paper_catalog | Materials | Queries the master substrate catalog (variantId, gsm, caliperUm, bulkFactor, grainDirection) with automatic bilingual (ES ↔ EN) synonym expansion and exact gsm filtering. |
ppos_calculate_book_estimate | Pricing | Runs the 5-Axis Book Pricing Engine (PPOS_5AXIS_BPE_V2: paper kg, CTP plates, make-ready, press hours, finishing) and computes the Digital vs. Offset crossover threshold (Q*). |
ppos_get_marketplace_offers | Marketplace | Requests multi-printhouse quotes and flags BPE_UNAVAILABLE or BPE_STATIC_FALLBACK responses. |
ppos_calculate_crossover_curve | Pricing | Computes the full run-length scaling curve (100 to 5,000 copies) comparing Digital Toner vs. Sheetfed Offset (B1/B2). |
ppos_calculate_spine_geometry | Binding (SPINE-01) | Calculates net paper block thickness, sewn swelling, 0.5 mm-stepped spine width, and full flat cover dimensions (flaps, hardcover board, hinge score, dust jacket). |
ppos_calculate_logistics_cubing_quote | Logistics (EPAL) | Computes unit book mass, FEFCO 0201 carton packing, 1200×800 mm EUR-EPAL palletization, warehouse compliance (Zeitfracht, Arvato VVA, Amazon FBA), ΔQ⁻ / ΔQ⁺ run optimization, and segregated freight. |
ppos_plan_sheet_imposition | Prepress | Generates press sheet layouts (B1, B2, SRA3, WEB_ROTARY), signature decomposition, make-ready waste, and progressive creep/shingling compensation. |
ppos_inspect_preflight | Quality Assurance | Audits 6 PDF axes (spine tolerance ±1.0 mm, 3/5/15 mm bleed, 300%/260% TAC, 300 DPI) and optionally applies MAGIC_FIX mirror-bleed synthesis. |
ppos_validate_machine_substrate | Materials | Validates physical press compatibility (gripper minimums, max sheet bounds, web width, and gsm ceilings). |
ppos_manage_marketplace_order | Orders | Manages order lifecycle actions (create, get, select_offer, register_file, bind_preflight, recompute_readiness). |
Resources (4)
| Resource URI | Description |
|---|---|
ppos://catalog/papers | Master substrate catalog with verified/imported caliper and bulk metadata. |
ppos://spine/profiles | Canonical binding line profiles (livonia-alegro-softcover@2.0.0, livonia-colibri-hardcover@2.0.0, livonia-colibri-flexi@2.0.0). |
ppos://logistics/warehouses | European book distributor dock constraints (ZEITFRACHT_ERFURT, ARVATO_VVA_GUETERSLOH, AMAZON_EU_FBA_STD, STANDARD_COMMERCIAL_DOCK, TAIL_LIFT_STREET_DELIVERY). |
ppos://preflight/capabilities | Active ISO_12647_2_FOGRA39 rules, TAC limits, bleed minimums, and supported auto-fix policies. |
5. Orchestration with the Agent Skill (printprice-mcp-orchestrator)
While the MCP server exposes raw atomic tools, the printprice-mcp-orchestrator Agent Skill encodes PrintPrice OS domain rules so AI agents execute multi-step workflows deterministically without triggering validation errors.
Installing the Skill
The skill is bundled inside the npm package and GitHub repository at .agents/skills/printprice-mcp-orchestrator/SKILL.md. Copy it into your agent's skill directory:
mkdir -p .agents/skills/printprice-mcp-orchestrator
cp node_modules/@ppos/mcp-server/.agents/skills/printprice-mcp-orchestrator/SKILL.md \
.agents/skills/printprice-mcp-orchestrator/SKILL.md
Deterministic 5-Step Execution Pipeline
When a user asks for a print quote, spine calculation, or landed logistics estimate, the skill enforces this sequence:
- Resolve Substrate (
ppos_search_paper_catalog): Retrieves the exactvariantId,caliperUm, andbulkFactorfrom the catalog. - Compute Certified Geometry (
ppos_calculate_spine_geometry): Passes{ pages, variantId }(omitting manualcaliperUm/gsmto prevent422 CLIENT_VARIANT_CALIPER_MISMATCH) to obtainspineWidthMmand flat cover dimensions. - Price Manufacturing & Crossover
Q*(ppos_calculate_book_estimate/ppos_get_marketplace_offers): Calculates the 5-axis industrial breakdown, identifies the Digital vs. Offset crossover point, and rejects static fallback offers. - Compute 3D Cubing & Freight (
ppos_calculate_logistics_cubing_quote): Calculates FEFCO 0201 cartons, EUR-EPAL pallets,ΔQ⁻ / ΔQ⁺pallet-fill adjustments, and keeps manufacturing, packaging, and carrier freight costs strictly segregated. - Preflight, Imposition & Order Readiness: Runs
ppos_inspect_preflightorppos_plan_sheet_impositionon demand, requiring explicit user confirmation before callingppos_manage_marketplace_order(action: "create").
Example End-to-End Prompt
"Quote 1,200 copies of a 256-page novel, 150×230 mm trim size, 90 gsm cream uncoated paper, PUR softcover with 85 mm flaps, and palletized freight to Zeitfracht Erfurt (Germany)."