AI agents (MCP)

PrintSocket runs an MCP server, so an AI agent can list your printers, print text or a PDF, and check whether the job actually came out, without any code of yours in between. MCP (the Model Context Protocol) is the standard way AI clients connect to outside tools. The server is part of the API and uses the same keys:

https://api.printsocket.com/mcp

It speaks MCP's Streamable HTTP transport, both the current revision (2026-07-28) and the older ones that start with initialize (2025-11-25, 2025-06-18, 2025-03-26), and authenticates with an API key in the Authorization header. Clients that can only connect with OAuth, which includes most hosted chat apps, cannot use it yet.

Creating a key for an agent

Give the agent its own key, and confine that key to the printers it should use:

• The print scope. print is enough for every tool. A read key can look but not print.
• Only the printers it needs. In the dashboard, API keys › Create a key for an AI agent preselects the scope and opens the printer picker. Through the API, pass printer_ids to POST /api_keys. The agent then cannot see or print to anything else on the account, and other printers' ids answer as not found.
• Test mode first. An sk_test_ key includes the virtual printer, which runs a job through its whole lifecycle and prints nothing, so you can watch how the agent behaves for free. A real printer enrolled in the test pool prints on paper like any other, and the tools mark which is which.

The key is a credential like any other: the client stores it in its own configuration file, so treat that file as a secret, and revoke the key from the dashboard if it leaks.

Connecting a client

These clients have been tested end to end against production. Other MCP clients that take a server URL and an Authorization header should work the same way, but have not been tested yet.

claude mcp add --transport http printsocket https://api.printsocket.com/mcp \
  --header "Authorization: Bearer sk_test_..."

# ~/.codex/config.toml
[mcp_servers.printsocket]
url = "https://api.printsocket.com/mcp"
http_headers = { Authorization = "Bearer sk_test_..." }

Then ask in plain words: "what printers can I use?", or "print this packing slip on the label printer".

Whether the client asks you before each print is up to the client, not PrintSocket. The print tools are marked as acting on the outside world, which is what well-behaved clients use to decide to ask, but Codex CLI printed without asking in its default configuration, and Claude Code does not ask in its auto mode. The printer allowlist on the key is the limit that holds regardless of the client.

The tools

print_text is the one agents use most, since models write text well and PDFs not at all. It picks the paper the way a person would: the one you name, else the printer's default, else Letter or A4 if the printer has it, and never a size the printer did not report. On a page, Western European characters print as written and anything else, such as emoji or CJK text, prints as ?. A receipt (render: "escpos") prints plain ASCII only, so accented letters print as ? there too. Either way the tool's reply says how many characters were affected.

What the agent is told

A print tool's reply means the job was accepted, not that it printed, and every print tool says so. Agents are told to call get_job with wait_seconds before saying anything came out, and the reply spells out the difference between the outcomes:

• Succeeded on the virtual printer: the simulation finished; nothing was printed.
• Succeeded, spooler only: completion_confidence is "spooler", meaning the computer's print spooler finished, but the printer itself could not confirm it. This is normal for receipt printers and print-to-file queues.
• Queued: waiting for the printer or its computer to come online.

In testing, both Claude Code and Codex CLI reported these outcomes accurately rather than saying "printed".

Limits and retries

• Copies: 1 to 10 per job over MCP. A larger run is more often a mistake than a print run, so those go through POST /jobs.
• Print rate: a burst of 10 print jobs per key, then one more per minute. A looping agent stops after a handful of pages, not at the end of the month. The account's request limit applies too.
• URLs: print_document refuses localhost and private or local IP addresses, because the agent that fetches the URL runs on your network.
• Idempotency: print tools take an idempotency_key. Repeating a call with the same key within 24 hours returns the original job instead of printing again, so a dropped connection cannot double-print. Agents tend to build the key from the content and the date, so asking for an identical second print on the same day can return the first job instead. The reply says nothing new was printed.

Telling agent jobs apart

A job created over MCP is an ordinary job: it appears in the job list, fires the same webhooks, and counts toward the plan like any other. Its metadata marks where it came from:

GET /jobs?metadata[source]=mcp lists every job an agent created. The print tools refuse caller metadata that uses either key.