MCP Server

zplflow provides an official Model Context Protocol (MCP) server, allowing AI agents (such as Claude, Cursor, Goose, and custom autonomous agents) to interact with your label infrastructure directly in natural language.

MCP Endpoint: https://mcp.zplflow.io/v1/mcp/
Protocol Transport: Streamable HTTP (MCP specification, stateless mode)

Overview

The zplflow MCP server is a dedicated microservice that gives AI agents the ability to:

Check token balances and reserved allowances.
Inspect and query conversion jobs.
Convert PDF to ZPL and ZPL to PDF.
Estimate token costs prior to running conversions.
Inspect, create, and apply programmable ZPL pipelines.

The transport uses modern Streamable HTTP rather than legacy SSE, offering native compatibility with standard MCP clients, sub-15ms overhead, and full multi-tenant isolation.

Authentication

Every request to the MCP server must include your zplflow API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

All MCP tools enforce the exact same per-key scopes as the REST API. See Authentication & Scopes for details.

Available Tools (10)

Tool	Required Scope	Tenant Feature	Description
`getAccountBalance`	`account:read`	—	Returns available token balance and reserved tokens in flight.
`listJobs`	`jobs:read`	`async_engine`	Returns recent conversion jobs for your tenant. Accepts `limit`.
`getJob`	`jobs:read`	`async_engine`	Returns full status and presigned URLs for a specific `job_id`.
`cancelJob`	`jobs:write`	`async_engine`	Cancels a queued job and returns reserved tokens.
`estimateCost`	`convert:estimate`	—	Computes exact token cost for conversions prior to execution.
`listPipelines`	`pipelines:read`	`pipelines`	Lists all pre-configured and custom ZPL transformation pipelines.
`getPipeline`	`pipelines:read`	`pipelines`	Retrieves the step configuration for a specific `pipeline_id`.
`getStorageUploadURL`	`jobs:create`	`async_engine`	Generates a presigned S3 URL to upload files for async conversion.
`submitConversion`	`jobs:create`	`async_engine`	Initiates an asynchronous conversion job.
`startJob`	`jobs:write`	`async_engine`	Starts processing on an uploaded conversion job.

Quick Start & Verification

You can verify your connection to the MCP server with a standard JSON-RPC 2.0 POST request over Streamable HTTP:

curl -X POST "https://mcp.zplflow.io/v1/mcp/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

A successful response returns the full JSON-RPC catalog of registered tools.

Client Setup

Claude Desktop

Add the zplflow MCP server to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "zplflow": {
      "type": "remote",
      "url": "https://mcp.zplflow.io/v1/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Restart Claude Desktop. The hammer icon will show the 10 zplflow tools ready for conversational queries.

Cursor / Autonomous Agents

For Cursor or other agents supporting remote MCP endpoints:

Select Remote MCP Server.
Set the Server URL to https://mcp.zplflow.io/v1/mcp/.
Add the header Authorization: Bearer YOUR_API_KEY.
Protocol: Streamable HTTP.

Example Agent Interactions

Once connected, your AI agent can perform operational tasks via natural language:

“How many tokens do I have left on our zplflow account?”
$\rightarrow$ calls getAccountBalance
“Estimate the cost to convert 5,000 PDF shipping labels to ZPL at 203 DPI.”
$\rightarrow$ calls estimateCost
“Show me the last 5 jobs and check if any failed.”
$\rightarrow$ calls listJobs
“What steps are included in our ‘gs1-compliance’ pipeline?”
$\rightarrow$ calls getPipeline