Connect an AI agent (MCP)

Your ProxyBox Zero exposes an MCP (Model Context Protocol) server so AI agents can list printers and print. MCP is off by default. Turn it on in the Agent Access (MCP) card at the bottom of your device’s admin page (open it with the arrow on the right).

Get an MCP URL

Open your ProxyBox admin page and sign in. For a remote agent, use your device’s public address when opening the admin page.
Open the Agent Access (MCP) card at the bottom of the page and set MCP to On. If no enabled MCP key exists, select Generate MCP URL; otherwise, the existing address appears.
The address appears in the Address row. A newly generated key is revealed immediately; use the eye button to hide or show it, and the copy button to copy the full address even while the key is hidden.

Generating a URL creates an API key named MCP (or MCP 2, MCP 3, and so on when a name is taken) and turns MCP on. The URL uses the address where you opened the admin page:

https://<your-device-host>/api/mcp/<key>

The URL contains your API key. Treat it like a password. Disabling or deleting that key in Settings → API Keys cuts off every agent using it on its next request.

Connect your client

After MCP is on and a key is available, the Connect row shows Claude.ai, ChatGPT, Grok, Claude Code, and Other clients panels. When remote access is configured, the cloud panel has a copy button for the connector address; the other panels let you copy a ready-to-run Claude Code command and the endpoint for clients that send an API-key header.

Claude.ai

Add a custom connector in Claude.ai.
Set its URL to the generated MCP URL, including the key at the end.
Set authentication to None.

ChatGPT

In ChatGPT developer mode, add a custom connector.
Set its URL to the generated MCP URL, including the key at the end.
Set authentication to None.

grok.com

Add a custom connector in grok.com.
Set its URL to the generated MCP URL, including the key at the end.
Set authentication to None.

Claude Code

Enable MCP, then run this command with your device’s address and an enabled API key from Settings → API Keys:

claude mcp add --transport http proxybox https://<your-device-host>/api/mcp \
  --header "X-API-Key: <key>"

Any MCP client with headers

Enable MCP and set the endpoint to https://<your-device-host>/api/mcp. Send an enabled API key in either of these headers:

X-API-Key: <key>

Authorization: Bearer <key>

What your agent can do

Tool	What it does
`get_status`	Get Status
`list_printers`	Get Printers
`get_printer`	Get Single Printer
`print`	Send Print Job
`get_job`	Get Job Status
`discover_printers`	Discover Printers
`test_print`	Send Test Print

Use a printer’s path or a tag_<name> alias as the print target, such as tag_LABELS. For large documents, supply the document URL as content with contentType set to pdf_url for PDFs or raw_url for raw printer data. ZPL fetched from a URL uses raw_url.

Requirements and limits

Remote agents need remote access through your device’s public address. If the Claude.ai, ChatGPT, Grok panel in the Connect row says Remote access is not configured, local agents on the same LAN can still use the local device address.

MCP always requires an enabled API key, even when Settings → Options → API Key is Optional for the REST API. MCP does not offer OAuth; connectors configured with authentication None authenticate using the key in the URL.

See what agents have done

While MCP is on, the Activity row at the bottom of the card shows the latest 50 agent actions under Time, Client, Tool, Target, and Result; the result is the HTTP status code, or 0 if the request fails before receiving a response. Select Refresh to update it. The device keeps the last 200 actions in memory and clears them when the device software restarts. It never records the contents of what was printed.

Turn off agent access

Set MCP to Off in the Agent Access (MCP) card to turn off MCP for all agents. To revoke access for agents using a particular key, turn that key off or delete it in Settings → API Keys.