TerradsTerrads
← Guides

Use Terrads in Claude Code

GuidesUpdated October 16, 2026

Once Terrads is connected, you can ask Claude Code to make ads for your brand in plain words: "make three feed ads for our new serum". It finds your brand, product and angle, can show you the price and wait for your go, starts the run, answers its questions with you, and hands back the finished images, videos or audio ads. It can also check on, answer or cancel runs you started earlier, here or in the app. Everything it makes lands in Creatives, next to the ads you make in the app.

Before you start

  • A plan that includes API access. Without one, Terrads refuses every request from the agent. If your plan doesn't include it, Settings → API keys tells you which plan does.
  • An API key. Create one in Settings → API keys. It's shown once, so copy it before you close the dialog. A key acts for your whole team: whatever the agent makes or cancels, everyone on the team sees.

Set it up with the plugin (recommended)

The plugin connects Terrads and teaches Claude Code how to use it: confirm the brief, agree a credit ceiling before spending, and walk you through each question. In a Claude Code session, add the marketplace:

/plugin marketplace add terrads-hq/agent-mode

Then, in the same session, install the plugin:

/plugin install terrads@terrads

Run them one at a time: each is its own command. /plugin install may ask where to install the plugin: installing it for you works in every project. Then paste your API key when Claude Code asks for it. If it doesn't ask, run /plugin, open Installed, pick terrads and set the key under Configure options. Claude Code keeps the key for you, so there's no environment variable to set.

Or connect the server yourself

If you'd rather not use the plugin, add the server from your project directory:

claude mcp add --transport http terrads https://terrads.com/api/mcp --header 'Authorization: Bearer ${TERRADS_API_KEY}'

The command saves a reference to TERRADS_API_KEY, not the key itself; it doesn't read the variable when you run it. Claude Code reads it each time it connects to Terrads, from the environment Claude Code runs in. So export TERRADS_API_KEY in your shell profile (for example ~/.zshrc), open a new terminal, and start Claude Code from there.

By default claude mcp add adds the server for this project only. To use Terrads in every project, add --scope user after claude mcp add.

This connects the server only. The plugin is the server plus a skill that knows the Terrads steps, so use one way or the other, not both.

Check it works

Start a new Claude Code session and run /mcp: Terrads should be listed as connected. Then ask:

List my Terrads brands.

The agent calls Terrads and answers with your team's brands by name. If it says it has no Terrads tools, or the call fails, see Troubleshooting below.

Then make something real:

Make two feed ads for one of my products, on one of its saved angles. Show me the price before you start.

The agent looks up your products, angles and models, tells you the brief and an estimated price, and waits for your yes (the plugin teaches it to; without the plugin, ask it to). After that it starts the run, checks on it while it works, brings any questions or ad text to you for approval, and finishes with links to the finished ads. Those links expire, so ask it to download the files if you want to keep them.

Things to ask

  • "Make ads for the Summer Serum in Feed and Story sizes, in English and German. Let me approve the text first."
  • "Make a short video ad for the Summer Serum. Show me the plan and the price before you approve it."
  • "Make an audio ad for the new candle and read me the script before it's made."
  • "What's the status of my last run? If it's waiting on me, show me what it needs."
  • "Download the finished ads from my last run into an ads folder in this project."
  • "Cancel the run I just started."

The agent can only work with brands, products, angles and audiences you've already set up in Terrads; set those up in the app first (set up your brand). For the full list of what the agent can do, see the MCP server reference.

Troubleshooting

The agent says it has no Terrads tools. In a terminal, claude mcp list lists your servers and whether each one connects; inside a session, /mcp shows the same and can reconnect a server. If Terrads isn't listed, the plugin isn't enabled or the server was added in another project (see --scope user above). Terrads has no sign-in step: if your client offers to authenticate the server, skip it and check the key instead.

Terrads refuses the connection with invalid_api_key. Your client may show this as the Terrads server failing to connect rather than as the code. The key didn't reach Terrads. Without the plugin, the usual cause is that TERRADS_API_KEY isn't set in the environment Claude Code started from: nothing prompts you, the reference is sent as written, and Terrads refuses it. Export it as above and start Claude Code again. The same error means the key was revoked, or the person who created it left the team; create a new one.

Terrads refuses the connection with upgrade_required or no_subscription. Your team's plan doesn't include API access, or there's no active plan. Your team's owner can change it in Settings → Billing; your existing key starts working again as soon as the plan does.

Terrads refuses the connection with past_due. The last payment failed. Your team's owner updates the card in Settings → Billing, and the key works again.

The agent reports insufficient_credits. The run costs more credits than your team has, and nothing was charged. Buy more or ask for a smaller run; see how credits work.

Terrads refuses requests with rate_limited. The agent made too many calls in a short time. Wait a moment and ask again.

Every other code and what it means is on the errors page.