Connect an AI agent

This page is for a seller who already has a Zarii shop and its seller admin: the key it walks you through creating only works for a shop you can already sign into. New to Zarii itself? Start at what Zarii is for an agent.

What it does

An AI agent (Claude, Codex, or whichever one you already talk to) can read and edit your catalogue directly: add products, set prices and stock, attach your own photographs, and publish. It never touches orders, payments or your payment QR, because there is no tool here that reaches any of those. Only your catalogue.

You still decide what gets typed. The agent does the typing.

Get a key

In your shop’s seller admin (sign in at your shop’s own address, not here), go to Settings → API keys → Create key. Give it a name (“Claude” or “my laptop agent” is fine) and leave the two ticked boxes as they are: read your catalogue and add and edit products, SKUs, prices, stock and photos. That is everything an agent needs for cataloguing work, and it is deliberately all it can do; there is no box that reaches orders or your payment rails.

Setting a product’s delivery method — shipped or digital, unlimited copies or a fixed number — is a catalogue edit like any other, so these same two boxes cover it. Marking a digital order’s file as sent is not: it is a separate box, “Move orders through packing and delivery, and mark digital items sent”, and it is not one of the two ticked by default. Tick it too if you want this key’s agent to do that step. See Selling digital items for what that looks like from your side.

The key is shown once, on that screen, and never again. Copy it before you leave the page. It looks like zari_sk_…, a long random string after that prefix.

You can revoke it at any time from the same page. The moment you do, the next request it makes is refused. Nothing further can happen with a revoked key, including anything the agent had queued.

Connect it

Every client below needs the same two things: the address https://mcp.zarii.ai/mcp, and your key as a bearer credential. How you hand those over is different in every client, and it is the part nobody can guess, so this section is checked against each client’s own current documentation, not guessed at. Where a client’s own docs are the only real authority (its exact flag names can change between releases), this says so and points there.

Claude Code

Run this in a terminal, with your real key in place of the placeholder:

claude mcp add --transport http zarii https://mcp.zarii.ai/mcp --header "Authorization: Bearer zari_sk_…"

Verified against Claude Code’s own docs (code.claude.com/docs/en/mcp) as of this writing. -H works as a short form of --header, and claude mcp list confirms the connection saved.

Running it locally instead, for add_product_photo’s folder-of-files path below, needs a copy of the Zarii MCP server running as a program on your own computer, a one-time setup someone technical does for you, since Zarii does not publish it as an installable package yet. Once you have the exact command that starts it, add it with:

claude mcp add --env ZARI_API_KEY=zari_sk_… --transport stdio zarii -- <the command you were given>

Codex

Add an entry to Codex’s own config file (typically ~/.codex/config.toml):

[mcp_servers.zarii]
url = "https://mcp.zarii.ai/mcp"
bearer_token_env_var = "ZARI_API_KEY"

Then set ZARI_API_KEY=zari_sk_… in the environment before you start Codex, rather than pasting the key into the file itself. This is verified against OpenAI’s current Codex documentation (developers.openai.com/codex); the table name and field names there are the authority if a later Codex release renames either.

Because Codex runs in a terminal with a shell of its own, it can run the curl command prepare_product_photo_upload hands back itself. See the upload path below.

Claude web

This is the one client where the honest answer depends on your account, and it is worth reading in full before you try it.

Open Settings → Connectors (an Organization owner on a Team or Enterprise plan instead adds it under Organization settings → Connectors, and everyone else connects to it afterwards from Customize → Connectors). Choose Add custom connector, and paste in https://mcp.zarii.ai/mcp as the server’s address.

For Authentication, choose None: Zarii’s server does not speak OAuth, so the OAuth options on that screen are not for it.

Now look for a Request headers section. What you see next depends on which one is true:

• If you see it: add a header named authorization with the value Bearer zari_sk_…: the word Bearer, a space, then your key. Claude sends that value exactly as typed, with no scheme added for you, which is why the word Bearer has to be part of what you type.
• If you don’t see it: your account does not have this feature yet: Anthropic is rolling it out gradually, to a limited set of organizations, as of this writing. Without it, there is no field on this screen for a key like Zarii’s, and Claude web cannot connect to your shop through this path yet. Use Claude Code, Codex, or ChatGPT web instead, or check back later. This is the kind of thing that ships without warning.

Verified against Anthropic’s own connector documentation (claude.com/docs/connectors/building/authentication and claude.com/docs/connectors/custom/remote-mcp) as of this writing.

ChatGPT web

Turn on developer mode under Settings → Apps → Advanced settings, then add a custom connector with https://mcp.zarii.ai/mcp as its URL.

Here the honest answer is a limitation rather than a fork in the road: OpenAI’s own documentation describes a custom connector’s authentication as OAuth or no authentication, and states plainly that ChatGPT cannot present a custom API key. Zarii’s server has no OAuth to offer, and a connection with no authentication at all is refused by Zarii on its first request. Put together, there is currently no way to connect ChatGPT web to your shop’s key. That may change. OpenAI’s connector documentation is the place to check before trying again, since this page cannot promise today’s gap is still there when you read it.

Where a connection is possible, on any of the clients above, the same key opens the same catalogue. Nothing about what the agent can do changes with which one you picked.

Getting a photograph onto a SKU

Zarii never invents a product photo. Whichever client you use, the agent needs your actual photograph, and it gets one to Zarii in one of four ways, depending on where that photograph already is.

A folder of photos on your own computer. Only possible when the agent is running the local, stdio copy of the Zarii server described above: the hosted address shares no filesystem with your laptop, so a remote agent cannot browse a folder on it. Where that local setup exists, the agent reads the file itself and attaches it in one step.

A photograph you can upload yourself, from a machine with a shell (Claude Code or Codex, whether local or connected to the hosted address). The agent measures the file, asks Zarii for a single-use upload link, and hands you (or runs itself) a ready-made command that sends the bytes straight to storage; once that lands, a second call finishes the record. Nothing about your photograph passes through the agent’s own memory in between.

A photograph already online at a public link. Give the agent the https:// address that opens the image itself, not a page that merely shows it, and Zarii fetches it directly. This is the one path that needs no shell and no shared filesystem, so it works in every client, including both web ones, wherever a connection to Zarii exists at all.

A photograph on your phone, inside Claude web. The agent opens an upload panel right there in the chat; you pick the file and your own browser sends it. This needs an authenticated connection to already exist, so it inherits whichever outcome the Claude web section above gave you, and it is not available in ChatGPT web today, for the same reason nothing else is.

What the agent cannot do

Trust here is built by naming the edges, not by asserting them:

• It never moves money. There is no order tool and no payment tool in this agent at all: not gated behind a scope you could tick differently, simply absent. Your payment QR is likewise untouched; nothing here can see it, let alone change it.
• It cannot create another key. An API key can read and write your catalogue, but minting a new key takes a person signed into the seller admin themselves. A key that hands itself a second key, or anything else, is exactly the kind of quiet escalation this refuses.
• A published product needs a photograph. Publishing checks for a real, stored cover image, a description, and shipping weight and measurements on every SKU still on sale that ships. A digital SKU needs none of the last part. The agent can supply the photograph and description; shipping measurements on anything that ships are set by hand in the seller admin, so a shipped product the agent built may still need that one step from you before it can go live.
• A SKU that already has a photograph is refused, not replaced. There is no way yet, through the agent or otherwise, to swap out a product photo once one is attached, only to add the first one. Replacing a photo means doing it in the seller admin.