# Atomatize: instructions for AI agents

You are reading this because a user wants you to use Atomatize for them. Follow these steps in order. Human-readable guides are at https://atomatize.com/docs.

Atomatize turns a source (pasted text, an article URL or a YouTube link) into twelve drafts in the user's voice: 4 LinkedIn posts, 5 X posts, an X thread, a newsletter section and an article. It can also publish or schedule them to the user's LinkedIn and X accounts. You use it through its MCP server:

- URL: `https://atomatize.com/api/mcp`
- Transport: Streamable HTTP
- Auth: MCP OAuth (the user signs in in their browser), or a bearer API key (`Authorization: Bearer atz_...`)

## 1. Check whether you're already connected

If you already have Atomatize tools (such as `list_brands` and `generate_drafts`), skip to step 3.

## 2. Connect

Pick the case that matches you.

### You can change your own MCP configuration

For example Claude Code, OpenClaw, or another agent that runs commands or edits its config. Add the server, then start the sign-in:

- **Claude Code:** run `claude mcp add --transport http atomatize https://atomatize.com/api/mcp`, then ask the user to run `/mcp` and choose **atomatize** to sign in.
- **OpenClaw:** run `openclaw mcp set atomatize '{"url":"https://atomatize.com/api/mcp","transport":"streamable-http","auth":"oauth"}'`, then `openclaw mcp login atomatize`.
- **Any other MCP client:** add `https://atomatize.com/api/mcp` as a Streamable HTTP server. Clients that support MCP authorization sign in the same way.

Tell the user before you start: a browser window will open; they sign in to Atomatize (or create an account), tick the brands you may use and what you may do, and approve. Suggest they leave **Publish** unticked unless they want you to post for them.

### You're a chat assistant and can't add connectors yourself

For example Claude or ChatGPT on the web or desktop. Give the user these steps, then wait for them to finish:

- **Claude:** Settings > Connectors > **Add custom connector**. Paste `https://atomatize.com/api/mcp`, then **Connect** and approve in the browser.
- **ChatGPT:** Settings > Apps & Connectors. Under Advanced settings, turn on developer mode, then create a connector with the URL `https://atomatize.com/api/mcp` and OAuth authentication, and approve in the browser.

Once the user says it's done, the Atomatize tools should be available. In some apps a new chat is needed.

### You run unattended and can't open a browser

For example a scheduled job or a server. Ask the user to create an API key at https://atomatize.com/dashboard/settings/agents (**Settings > API & agents**) with only the permissions the job needs and only the brands it should use. Ask them to put the key in your configuration or environment themselves, as an `Authorization: Bearer atz_...` header. Don't ask them to paste it into a chat. Without an MCP client, a script can POST JSON-RPC `tools/call` requests directly; https://atomatize.com/docs/api-keys has a working example.

## 3. Use it

1. Call `list_brands`. If there is more than one brand, every other call needs `brand` (an id or exact name). If the user didn't say which brand, ask them. Don't guess.
2. Call `generate_drafts` with `text` or `url` (and the `brand`). It answers at once with a `content_id` and status `processing`. PDFs aren't supported here; the user uploads them in the web app.
3. Call `get_content` every 10 to 20 seconds until `status` is `ready`. It usually takes one to two minutes. If the status is `stale`, `failed` or `partial`, call `retry_generation`. Every response has a `next_step`; follow it.
4. Show the user the drafts they asked about. Refine with `update_output`, `regenerate_output`, `create_variant` (another version, keeping the original) and `star_output`. When the user says what they want changed ("shorter", "less formal"), pass it as `instructions` to `regenerate_output` or `create_variant` rather than editing the text yourself.
5. To publish: call `list_targets`, then `publish_output` or `schedule_output` with a `target_id`, only after the user confirms (see the rules below).

`get_usage` shows the plan, the monthly limit and how much is used. `list_content` and `get_content` find earlier sources and their drafts.

## Rules

- **Ask before publishing.** `publish_output` and `schedule_output` post publicly under the user's name. Before calling either, show the user the exact text, the account (target) and the brand, and get an explicit yes. Never publish or schedule in an unattended run unless the user set that up on purpose.
- **Don't add facts.** When you edit a draft, don't add claims, numbers, clients or events the source doesn't contain. The drafts are written to stay true to the source.
- **Mind the monthly limit.** Each `generate_drafts` call counts once toward the plan's monthly limit (shared by all brands). Rewrites, other versions and edits don't count. Before generating many sources at once, check `get_usage` and tell the user.
- **Ask before deleting.** `delete_output` and `delete_content` can't be undone.
- **Stay in the brand.** Use the brand the user named, and don't move content between brands.

## Errors

Every error has a `code`, a `message` written for the user and usually a `hint` saying what to do next. Follow the hint. The ones that need the user:

| Code | What to do |
|---|---|
| `INSUFFICIENT_SCOPE` | You lack a permission (often publish). Tell the user; they can reconnect and tick it, or use a key that has it |
| `BRAND_REQUIRED`, `AMBIGUOUS_BRAND` | Ask the user which brand, then pass its id |
| `NO_BRAND_ACCESS` | The connection covers no brands. The user adds one in Settings > API & agents |
| `LIMIT_EXCEEDED`, `TRIAL_EXPIRED`, `SUBSCRIPTION_INACTIVE` | The plan blocks generating. Pass on the message and the link in the hint |
| `PLAN_REQUIRED` | The plan doesn't include publishing. Offer the draft text for the user to post by hand |
| `TARGET_UNAVAILABLE`, `TOKEN_WILL_EXPIRE` | The user reconnects the account in the brand's publishing settings |
| `BRAND_LOCKED` | The brand is read-only on the user's plan |
| `NO_CHANGE` | Your `instructions` asked for something the source doesn't support, so nothing changed. Tell the user; they can edit the text themselves |

Limits: 60 calls a minute per connection, and at most 3 sources generating at once per brand (`TOO_MANY_GENERATIONS`: wait for one to finish).