Connect an AI agent (MCP)

Your ProxyBox 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

1. Open your ProxyBox admin page and sign in. For a remote agent, use your device’s public address when opening the admin page.
2. Open the Agent Access (MCP) card at the bottom of the page, turn MCP on, and select Generate MCP URL.
3. The address appears in the Address row with the key hidden. Use the copy button to copy it, or the eye button to reveal it.

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

Claude.ai

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

ChatGPT

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

grok.com

1. Add a custom connector in grok.com.
2. Set its URL to the generated MCP URL, including the key at the end.
3. 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 Settings shows 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 Require API Key is off 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

The Activity row at the bottom of the card lists recent agent actions: the time, which agent, which tool it used, what it targeted, and the result. Select Refresh to update it. The list keeps the last 200 actions and clears when the device 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.