Home›Developers›MCP Server

MCP Server

Labelixa runs a remote MCP (Model Context Protocol) server, so MCP-compatible AI clients can render, validate, debug and convert thermal label code — ZPL, EPL, TSPL and CPCL — and generate barcodes as first-class tools. Verified with Claude Desktop and Claude Code; any MCP-compatible client can connect.

Configuration

Add the server to an MCP-compatible client (Claude Desktop format shown). A local stdio alternative is published on npm as labelixa-mcp.

{
  "mcpServers": {
    "labelixa": {
      "type": "http",
      "url": "https://api.labelixa.com/mcp"
    }
  }
}

Claude Code, one line in a terminal:

claude mcp add --transport http labelixa https://api.labelixa.com/mcp

With an API key (the same Authorization header works in a JSON client entry under "headers"):

claude mcp add --transport http labelixa https://api.labelixa.com/mcp --header "Authorization: Bearer lbx_YOUR_KEY"

Example prompts

Once connected, ask in plain language — the client picks the tool. Every prompt below was run against this server:

Validate this ZPL and explain the diagnostics: ^XA^FO40,40^A0N,40,40^FDHello^FS^XZ
Render this ZPL and show me the label.
What does ^BC do, and does Labelixa's preview render it?
Which printer language is this code written in?
Generate a QR code PNG for https://labelixa.com/mcp

Clients

We publish setup snippets only for clients we have tested ourselves. The others are not a rejection: any client that speaks remote MCP over streamable HTTP needs nothing but the endpoint above — we simply have not run them, and will not describe a setup we did not see work.

Client	Status
Claude Desktop	Verified by us
Claude Code	Verified by us
Cursor	Not tested by us
VS Code	Not tested by us
Windsurf	Not tested by us
ChatGPT / Codex	Not tested by us
Gemini CLI	Not tested by us

Available tools

These are the tools the server exposes today — the list below is generated from the live tool registry, not copied by hand:

zpl_preview — Render ZPL label code and return the label as a PNG image.
zpl_validate — Lint ZPL code and return structured diagnostics: unknown commands, missing ^FS, out-of-range parameters, fields outside the label boundary.
zpl_command_help — Explain a single ZPL command: syntax, parameters with types/ranges/options, a fragment example and whether the Labelixa renderer draws it.
barcode_png — Generate a single barcode as a PNG image (Code 128, QR, DataMatrix, EAN-13, UPC-A, PDF417 and more).
language_detect — Detect which printer language raw label code is written in (ZPL, EPL, TSPL or CPCL).
epl_validate — Lint EPL/EPL2 label code and return positioned findings with severity as JSON.
tspl_validate — Lint TSPL/TSPL2 label code and return positioned findings with severity as JSON.
cpcl_validate — Lint CPCL label code and return positioned findings with severity as JSON.
explain_zpl — Full health report for a ZPL label: sectioned findings (syntax, size/DPI, orientation, barcodes, fonts, graphics memory, job behaviour) with an honest score — sections that cannot be assessed say so and are excluded from the score.
convert_zpl_dpi — Rescale ZPL between printer resolutions (203/300/600 DPI): coordinates, fonts, barcode module width and label size are scaled.
template_list — List Labelixa's first-party label template catalog: id, English name, category, size/density and tags.
template_get — Fetch one catalog template: metadata, preview image URL and — for non-premium templates — the ZPL source, ready for zpl_preview.
epl_preview — Render EPL/EPL2 label code and return a PNG preview.
tspl_preview — Render TSPL/TSPL2 label code and return a PNG preview.
cpcl_preview — Render CPCL label code and return a PNG preview.
image_to_zpl — Convert an image (PNG, JPEG, BMP or GIF, max 200 KB) to a ZPL ^GF graphic command.
barcode_verify — Decode barcodes from a photo or scan of a PRINTED label (PNG, JPEG, BMP or GIF) and report what a software decoder reads back.
zpl_compatibility — Compatibility RISK analysis of ZPL code against a specific printer model, given as manufacturer/model (e.g.
bulk_submit — Submit a bulk label production job: one ZPL template with {{variable}} placeholders plus data rows (one object per label).
bulk_status — Status of one bulk job you own: state, attempt count and — when finished — the summary with produced count and per-row failures (row number + reason; failed rows never block the rest).
bulk_list — List your recent bulk jobs (id, state, error class, timestamps), newest first.

Endpoint

Streamable HTTP (JSON-RPC) at https://api.labelixa.com/mcp. GET serves this page; the protocol speaks over POST.

Authentication and quotas

No key is required: anonymous calls share the free, per-IP rate-limited tier. Send your key in the X-API-Key header (or as a Bearer token) to use your plan's quota instead. MCP calls pass the same rate and quota gates as the REST API — MCP is not a quota bypass.

What happens after you connect

The client calls tools/list and the tools above appear next to its built-in ones. A tool call goes through the same path as the REST API — same authentication, same rate limits, same quota counters — and returns either text (JSON diagnostics) or a PNG image the client displays inline. Nothing is stored between calls: the server is stateless and every call stands alone.

Limitations

Streamable HTTP over POST only. A GET with Accept: text/event-stream answers 405 with Allow: POST — there is no SSE session channel.
Request envelope: 2 MB. Image input for image_to_zpl: 200 KB; for barcode_verify: 5 MB.
zpl_preview is a SERVER-SIDE render for inspection, not a guarantee of what a specific physical printer will output.
Tools behind a closed feature flag are absent from tools/list and answer "unknown tool" if called — the list is the contract.
Bulk jobs can be submitted and polled over MCP; the produced output is downloaded over the REST API.

Troubleshooting

404 on the endpoint — the server flag is closed; nothing to configure on your side.
405 on GET — expected. The protocol speaks over POST.
Rate limit (429, e.g. "3/sec") — anonymous calls are limited per IP. Slow down, or send an API key to use your plan's quota.
"Unknown tool" — the name is not in tools/list (typo, or a flag-gated tool).
A tool answers with an error instead of a result — the text is the server's own message, passed through unchanged. It tells you what failed; we do not rewrite it.

Security and privacy

Tool calls follow the same stateless path as the REST API: submitted label code is processed in memory and returned, not stored. Details on the security page.