API and MCP

The plugin connects your agent to SmartGenius and brings the skill that teaches it how to use SmartGenius. There's no key to copy.

Claude Code

claude plugin marketplace add owe-br/plugins
claude plugin install smartgenius@owe-br

Then type /mcp, pick smartgenius and choose Authenticate.

Codex

codex plugin marketplace add owe-br/plugins
codex plugin add smartgenius@owe-br
codex mcp login smartgenius

The last line signs you in. It needs Codex 0.147 or later: older versions fail with “missing required issuer”. To update, run npm install -g @openai/codex@latest.

Either way, your browser opens SmartGenius: sign in, pick the workspace and click Allow. That makes a key named after the app, listed under API and MCP in the workspace menu. To disconnect, revoke that key there. Only a workspace's admins can connect an app.

See the plugin on GitHubWhat the app sees and what we keep

MCP is how an AI app uses outside tools. In apps that sign in through the browser, add a custom connector with our MCP server's address and no key:

https://api.smartgenius.app/mcp

When you connect, the app opens SmartGenius and you sign in the same way: pick the workspace and click Allow. The key named after the app shows up under API and MCP, and you can revoke it whenever you like.

What the app sees and what we keep

An agent on a server, in a container or over SSH can't open a browser for you. It can still connect without a key you copy: it shows a code, you allow it in SmartGenius, and it gets its own key. This works only with the client_id smartgenius-agent. The agent starts like this:

curl https://api.smartgenius.app/oauth/device_authorization \
  -d client_id=smartgenius-agent

The answer has a link and a code like WDJB-MJHT. Open the link on any phone or computer, or go to https://my.smartgenius.app/device and type the code. Sign in, check that the code matches the one the agent shows, pick the workspace and click Allow. Only a workspace's admins can allow it. The code lasts 10 minutes.

Allow it only if you started this connection yourself. If someone sent you the link or asked you for a code, don't allow it.

Meanwhile, the agent keeps device_code to itself and asks for its key every 5 seconds:

curl https://api.smartgenius.app/oauth/token \
  -d grant_type=urn:ietf:params:oauth:grant-type:device_code \
  -d client_id=smartgenius-agent \
  -d device_code=…

Until you allow it, the answer is authorization_pending. Then it's access_token: a normal key named “AI agent (device sign-in)”, listed under API and MCP. It works until someone revokes it there. If you click Don't allow, the answer is access_denied. If the 10 minutes run out, it's expired_token, and the agent has to start over.

Use a key when the program can't open a browser: a script, a server, an automation.

A workspace admin makes the key in SmartGenius, under API and MCP in the workspace menu. It's shown once: we keep only its first few characters.

A key acts as the person who made it, with the role they have in the workspace. If they leave, the key stops working right away. A workspace can have up to 10 keys. Whenever someone creates a key, the workspace's admins get an email.

Log in and make a key

One call, one image. Replace sg_… with your key:

curl https://api.smartgenius.app/v1/images \
  -H "Authorization: Bearer sg_…" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"a lighthouse at dawn, in watercolor"}'

The answer has a link to the image. The link works for 7 days, so download the image if you need it longer.

A program with no browser sends the key in the Authorization header, at the same address:

Claude Code on a server

claude mcp add --transport http smartgenius \
  https://api.smartgenius.app/mcp \
  --header "Authorization: Bearer sg_…"

Cursor and other apps

In Cursor, add this to ~/.cursor/mcp.json. Other MCP apps use the same address and the same header.

{
  "mcpServers": {
    "smartgenius": {
      "url": "https://api.smartgenius.app/mcp",
      "headers": {
        "Authorization": "Bearer sg_…"
      }
    }
  }
}

A skill is a file that teaches an agent how to use SmartGenius: the order of the calls, how to wait for a post, and what never to do. The plugin already includes it. For any other agent, install it with one command:

curl -fsSL https://smartgenius.app/skill/install.sh | sh

The file goes to ~/.agents/skills/smartgenius/, and Claude Code and Codex get a link to it. Using another agent? Point it at that file. To update, run the command again.

Read the script firstSee the skill

There are five operations. Over MCP, each one is a tool. Over HTTP, each one is a route. Both do the same thing.

list_profilesGET /v1/profiles

Lists the workspace's profiles. Every post needs one of their @s.

create_postPOST /v1/profiles/{profile}/posts

Starts a post from an idea. It answers right away, before the post is ready.

get_postGET /v1/profiles/{profile}/posts/{id}?wait=30

Shows the post: where it stands, each slide's text, the caption, the hashtags and a link to open it in SmartGenius. With wait (up to 50 s), the answer holds until the post is done.

generate_imagePOST /v1/images

Makes 1 to 4 images from a prompt. Add profile and they come out in that profile's style and colors.

get_usageGET /v1/usage

Images used and left this month, today's limit, and when the month resets.

GET /v1/profiles/{profile}/posts/{id}/export?size=4:5

Downloads the finished post as a zip: one JPEG per slide, and the caption in caption.txt.

create_post also takes format (carousel, post or story), slides, objective, tone, cta and links (up to 5 pages to read first). generate_image takes aspectRatio (1:1, 4:5, 9:16, 16:9 and more) and count. A profile works with or without its @.

1. Call list_profiles and pick a profile.
2. Call create_post with the profile's @ and the idea. The answer has the post's id.
3. Call get_post with wait=30 until making.status is done or failed. A carousel takes a few minutes.
4. The post lands as a draft. Approving, scheduling and publishing stay with a person, at the post's studioUrl.

Calling create_post again makes a second post and spends the images again. To repeat a call safely (after a network error, say), send a requestId: any text of your own, like a UUID. With the same requestId you get the first call's answer, and nothing is spent twice. It lasts 24 hours and works for generate_image too.

curl https://api.smartgenius.app/v1/profiles/@your.profile/posts \
  -H "Authorization: Bearer sg_…" \
  -H "Content-Type: application/json" \
  -d '{"idea":"5 tips for keeping homemade bread fresh","requestId":"4b1d7e2a-9c3f-4e8b-a6d5-1f0e2c3b4a59"}'

• Each image uses one from the workspace's monthly quota: one per slide of a post, one per standalone image. It's the same quota posts made in SmartGenius use, on every plan. A failed image isn't charged.
• Each key can make 120 calls a minute.
• Each key can hold 5 get_post waits at once. From the sixth on, get_post answers right away without waiting.
• generate_image makes 1 to 4 images per call.
• Image links work for 7 days. Download what you'll use: after that, the image is deleted.

Over HTTP, an error looks like this. Over MCP, you get the same object with isError: true: { error: { code, message, details } }

UNAUTHORIZED · INVALID_TOKEN

The key is missing, was revoked, or the person who made it left the workspace. Make a new key.

FORBIDDEN

The person who made the key isn't allowed to do that in this workspace. For example, someone who only approves posts can't spend images.

NOT_FOUND

That profile or post isn't in this workspace. Check the @ with list_profiles.

VALIDATION_ERROR

A field is wrong (details says which and why), or the requestId was already used for a different request.

CONFLICT

The first call with this requestId hasn't answered yet. Wait retryAfterSecs seconds, then call again with the same requestId.

QUOTA_EXCEEDED

The month's or the day's images ran out. details.resetAt says when they come back; a bigger plan or an image pack lifts it sooner.

RATE_LIMIT_EXCEEDED

Too many calls in a minute. Wait retryAfterSecs seconds and try again.

GENERATION_FAILED

The image model failed or refused the request. Nothing was charged. Try again or change the prompt.