API e MCP

O plugin conecta o seu agente ao SmartGenius e já traz a skill, que ensina o agente a usar o SmartGenius. Você não copia nenhuma chave.

Claude Code

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

Depois, digite /mcp, escolha smartgenius e depois Authenticate.

Codex

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

A última linha faz o login. Ela precisa do Codex 0.147 ou mais novo: nas versões antigas, falha com “missing required issuer”. Para atualizar, rode npm install -g @openai/codex@latest.

Nos dois, o navegador abre o SmartGenius: entre, escolha o espaço e clique em Permitir. Isso cria uma chave com o nome do app, que aparece em API e MCP, no menu do espaço. Para desconectar, revogue essa chave lá. Só quem administra o espaço pode conectar um app.

Ver o plugin no GitHubO que o app vê e o que guardamos

MCP é o jeito de um app de IA usar ferramentas de fora. Nos apps que entram pelo navegador, adicione um conector personalizado com o endereço do nosso servidor MCP, sem chave:

https://api.smartgenius.app/mcp

Na hora de conectar, o app abre o SmartGenius e você entra do mesmo jeito: escolhe o espaço e clica em Permitir. A chave com o nome do app aparece em API e MCP, e você pode revogá-la quando quiser.

O que o app vê e o que guardamos

Um agente num servidor, num contêiner ou via SSH não consegue abrir o navegador para você. Mesmo assim, ele conecta sem você copiar nenhuma chave: ele mostra um código, você permite no SmartGenius e ele recebe a própria chave. Isso só funciona com o client_id smartgenius-agent. O agente começa assim:

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

A resposta traz um link e um código como WDJB-MJHT. Abra o link em qualquer celular ou computador, ou acesse https://my.smartgenius.app/device e digite o código. Entre, confira se o código é o mesmo que o agente mostra, escolha o espaço e clique em Permitir. Só quem administra o espaço pode permitir. O código vale 10 minutos.

Só permita se foi você quem começou essa conexão. Se alguém mandou o link ou pediu um código, não permita.

Enquanto isso, o agente guarda o device_code só para ele e pede a chave a cada 5 segundos:

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=…

Até você permitir, a resposta é authorization_pending. Depois vem o access_token: uma chave comum, chamada “AI agent (device sign-in)”, que aparece em API e MCP. Ela funciona até alguém revogá-la lá. Se você clicar em Não permitir, a resposta é access_denied. Se os 10 minutos acabarem, vem expired_token, e o agente precisa começar de novo.

Use uma chave quando o programa não abre o navegador: um script, um servidor, uma automação.

Quem administra o espaço cria a chave no SmartGenius, em API e MCP, no menu do espaço. Ela aparece uma vez só: guardamos apenas o começo dela.

A chave age em nome de quem a criou, com o papel que essa pessoa tem no espaço. Se ela sair do espaço, a chave para de funcionar na hora. Cada espaço pode ter até 10 chaves. Sempre que alguém cria uma chave, quem administra o espaço recebe um e-mail.

Entrar e criar uma chave

Uma chamada, uma imagem. Troque sg_… pela sua chave:

curl https://api.smartgenius.app/v1/images \
  -H "Authorization: Bearer sg_…" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"um farol ao amanhecer, em aquarela"}'

A resposta traz um link para a imagem. O link vale por 7 dias: baixe a imagem se for usar depois disso.

Um programa sem navegador manda a chave no cabeçalho Authorization, no mesmo endereço:

Claude Code num servidor

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

Cursor e outros programas

No Cursor, coloque isto no arquivo ~/.cursor/mcp.json. Outros programas com MCP usam o mesmo endereço e o mesmo cabeçalho.

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

Uma skill é um arquivo que ensina o agente a usar o SmartGenius: a ordem das chamadas, como esperar um post e o que nunca fazer. O plugin já traz a skill. Em outro agente, instale com um comando:

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

O arquivo fica em ~/.agents/skills/smartgenius/, e o Claude Code e o Codex ganham um link para ele. Usa outro agente? Aponte para esse arquivo. Para atualizar, rode o comando de novo.

Ler o script antesVer a skill

São cinco operações. Pelo MCP, cada uma é uma ferramenta. Por HTTP, cada uma é uma rota. As duas fazem a mesma coisa.

list_profilesGET /v1/profiles

Lista os perfis do espaço. Todo post precisa do @ de um deles.

create_postPOST /v1/profiles/{profile}/posts

Começa um post a partir de uma ideia (idea). Responde na hora, antes de o post ficar pronto.

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

Mostra o post: em que pé está, o texto de cada slide, a legenda, as hashtags e o link para abrir no SmartGenius. Com wait (até 50 s), a resposta espera o post ficar pronto.

generate_imagePOST /v1/images

Cria de 1 a 4 imagens a partir de um prompt. Com profile, elas saem no estilo e nas cores daquele perfil.

get_usageGET /v1/usage

Quantas imagens foram usadas e quantas restam no mês, o limite do dia e quando o mês vira.

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

Baixa o post pronto num zip: um JPEG por slide e a legenda em caption.txt.

create_post também aceita format (carousel, post ou story), slides, objective, tone, cta e links (até 5 páginas para ler antes). generate_image aceita aspectRatio (1:1, 4:5, 9:16, 16:9 e outros) e count. O perfil funciona com ou sem o @.

1. Chame list_profiles e escolha o perfil.
2. Chame create_post com o @ do perfil e a ideia. A resposta traz o id do post.
3. Chame get_post com wait=30 até making.status ficar done ou failed. Um carrossel leva alguns minutos.
4. O post fica como rascunho. Aprovar, agendar e publicar continua com uma pessoa, no link studioUrl.

Chamar create_post de novo cria um segundo post e gasta as imagens outra vez. Para repetir uma chamada sem esse risco (depois de um erro de rede, por exemplo), mande um requestId: qualquer texto seu, como um UUID. Com o mesmo requestId, a resposta é a da primeira chamada e nada é gasto duas vezes. Ele vale por 24 horas e funciona também em generate_image.

curl https://api.smartgenius.app/v1/profiles/@seu.perfil/posts \
  -H "Authorization: Bearer sg_…" \
  -H "Content-Type: application/json" \
  -d '{"idea":"5 dicas para conservar pão caseiro","requestId":"4b1d7e2a-9c3f-4e8b-a6d5-1f0e2c3b4a59"}'

• Cada imagem sai da cota mensal do espaço: uma por slide de um post, uma por imagem avulsa. É a mesma cota dos posts feitos no SmartGenius, em qualquer plano. Imagem que falha não é cobrada.
• Cada chave faz até 120 chamadas por minuto.
• Cada chave segura até 5 esperas de get_post ao mesmo tempo. Da sexta em diante, get_post responde na hora, sem esperar.
• generate_image cria de 1 a 4 imagens por chamada.
• Os links das imagens valem por 7 dias. Baixe o que for usar: depois disso, a imagem é apagada.

Por HTTP, um erro chega assim. Pelo MCP, chega o mesmo objeto com isError: true: { error: { code, message, details } }

UNAUTHORIZED · INVALID_TOKEN

Falta a chave, ela foi revogada ou quem a criou saiu do espaço. Crie outra chave.

FORBIDDEN

Quem criou a chave não pode fazer isso neste espaço. Por exemplo: quem só aprova posts não gasta imagens.

NOT_FOUND

O perfil ou o post não está neste espaço. Confira o @ com list_profiles.

VALIDATION_ERROR

Algum campo veio errado (details diz qual e por quê), ou o requestId já foi usado num pedido diferente.

CONFLICT

A primeira chamada com esse requestId ainda não respondeu. Espere os segundos de retryAfterSecs e chame de novo, com o mesmo requestId.

QUOTA_EXCEEDED

Acabaram as imagens do mês ou do dia. details.resetAt diz quando elas voltam; um plano maior ou um pacote de imagens libera antes.

RATE_LIMIT_EXCEEDED

Chamadas demais num minuto. Espere os segundos de retryAfterSecs e tente de novo.

GENERATION_FAILED

O modelo de imagem falhou ou recusou o pedido. Nada foi cobrado. Tente de novo ou mude o prompt.