Skip to main content

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.

Source Code & Package
  • 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 VariableRequiredDefaultDescription
PPOS_BASE_URLNohttps://control.printprice.proTarget PrintPrice OS Control Plane endpoint.
PPOS_API_KEYYes—Developer API Key (pp_test_<32hex> for Sandbox or pp_live_<32hex> for Production).
PPOS_JWT_TOKENConditional—Operator/Admin Bearer JWT (<YOUR_OPERATOR_JWT_TOKEN>). Required for admin-scoped endpoints such as /api/v1/spine/calculate.
PPOS_MARKETPLACE_TOKENConditional—Machine-to-machine intake token for creating or updating Marketplace orders.
PPOS_HTTP_TIMEOUT_MSNo15000Upstream HTTP timeout in milliseconds (matches the 15s BPE guard).
Security & Multi-Tenant Isolation

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.

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>"
}
}
}
}

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 & PathPurpose
POST /mcpJSON-RPC Streamable HTTP endpoint for MCP initialize, tools/list, tools/call, and resources/read requests.
GET /mcpServer-Sent Events (SSE) stream for active mcp-session-id sessions.
DELETE /mcpTerminates an active MCP session cleanly.
GET /healthLiveness 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 NameDomainPurpose
ppos_search_paper_catalogMaterialsQueries the master substrate catalog (variantId, gsm, caliperUm, bulkFactor, grainDirection) with automatic bilingual (ES ↔ EN) synonym expansion and exact gsm filtering.
ppos_calculate_book_estimatePricingRuns 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_offersMarketplaceRequests multi-printhouse quotes and flags BPE_UNAVAILABLE or BPE_STATIC_FALLBACK responses.
ppos_calculate_crossover_curvePricingComputes the full run-length scaling curve (100 to 5,000 copies) comparing Digital Toner vs. Sheetfed Offset (B1/B2).
ppos_calculate_spine_geometryBinding (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_quoteLogistics (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_impositionPrepressGenerates press sheet layouts (B1, B2, SRA3, WEB_ROTARY), signature decomposition, make-ready waste, and progressive creep/shingling compensation.
ppos_inspect_preflightQuality AssuranceAudits 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_substrateMaterialsValidates physical press compatibility (gripper minimums, max sheet bounds, web width, and gsm ceilings).
ppos_manage_marketplace_orderOrdersManages order lifecycle actions (create, get, select_offer, register_file, bind_preflight, recompute_readiness).

Resources (4)​

Resource URIDescription
ppos://catalog/papersMaster substrate catalog with verified/imported caliper and bulk metadata.
ppos://spine/profilesCanonical binding line profiles (livonia-alegro-softcover@2.0.0, livonia-colibri-hardcover@2.0.0, livonia-colibri-flexi@2.0.0).
ppos://logistics/warehousesEuropean book distributor dock constraints (ZEITFRACHT_ERFURT, ARVATO_VVA_GUETERSLOH, AMAZON_EU_FBA_STD, STANDARD_COMMERCIAL_DOCK, TAIL_LIFT_STREET_DELIVERY).
ppos://preflight/capabilitiesActive 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:

  1. Resolve Substrate (ppos_search_paper_catalog): Retrieves the exact variantId, caliperUm, and bulkFactor from the catalog.
  2. Compute Certified Geometry (ppos_calculate_spine_geometry): Passes { pages, variantId } (omitting manual caliperUm/gsm to prevent 422 CLIENT_VARIANT_CALIPER_MISMATCH) to obtain spineWidthMm and flat cover dimensions.
  3. 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.
  4. 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.
  5. Preflight, Imposition & Order Readiness: Runs ppos_inspect_preflight or ppos_plan_sheet_imposition on demand, requiring explicit user confirmation before calling ppos_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)."