API y MCP

El plugin conecta tu agente con SmartGenius y trae la skill, que le enseña a usar SmartGenius. No tienes que copiar ninguna clave.

Claude Code

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

Luego escribe /mcp, elige smartgenius y después Authenticate.

Codex

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

La última línea inicia sesión. Necesita Codex 0.147 o posterior: en versiones anteriores falla con “missing required issuer”. Para actualizar, ejecuta npm install -g @openai/codex@latest.

En los dos casos, el navegador abre SmartGenius: inicia sesión, elige el espacio y haz clic en Permitir. Eso crea una clave con el nombre de la app, que aparece en API y MCP, en el menú del espacio. Para desconectarla, revócala ahí. Solo quien administra el espacio puede conectar una app.

Ver el plugin en GitHubQué ve la app y qué guardamos

MCP es la forma en que una app de IA usa herramientas externas. En las apps que inician sesión en el navegador, agrega un conector personalizado con la dirección de nuestro servidor MCP, sin clave:

https://api.smartgenius.app/mcp

Al conectar, la app abre SmartGenius y entras de la misma forma: eliges el espacio y haces clic en Permitir. La clave con el nombre de la app aparece en API y MCP, y puedes revocarla cuando quieras.

Qué ve la app y qué guardamos

Un agente en un servidor, en un contenedor o por SSH no puede abrirte el navegador. Aun así, puede conectarse sin que copies ninguna clave: muestra un código, tú lo permites en SmartGenius y recibe su propia clave. Esto solo funciona con el client_id smartgenius-agent. El agente empieza así:

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

La respuesta trae un enlace y un código como WDJB-MJHT. Abre el enlace en cualquier celular o computadora, o entra en https://my.smartgenius.app/device y escribe el código. Inicia sesión, revisa que el código sea el mismo que muestra el agente, elige el espacio y haz clic en Permitir. Solo quien administra el espacio puede permitirlo. El código dura 10 minutos.

Permítelo solo si tú iniciaste esta conexión. Si alguien te mandó el enlace o te pidió un código, no lo permitas.

Mientras tanto, el agente guarda el device_code para sí y pide la clave 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=…

Hasta que lo permitas, la respuesta es authorization_pending. Después llega el access_token: una clave normal llamada “AI agent (device sign-in)”, que aparece en API y MCP. Funciona hasta que alguien la revoque ahí. Si haces clic en No permitir, la respuesta es access_denied. Si se acaban los 10 minutos, llega expired_token y el agente tiene que empezar de nuevo.

Usa una clave cuando el programa no puede abrir un navegador: un script, un servidor, una automatización.

Quien administra el espacio crea la clave en SmartGenius, en API y MCP, dentro del menú del espacio. Se muestra una sola vez: solo guardamos el comienzo.

La clave actúa en nombre de quien la creó, con el rol que esa persona tiene en el espacio. Si sale del espacio, la clave deja de funcionar al instante. Cada espacio puede tener hasta 10 claves. Cada vez que alguien crea una clave, quienes administran el espacio reciben un correo.

Entrar y crear una clave

Una llamada, una imagen. Cambia sg_… por tu clave:

curl https://api.smartgenius.app/v1/images \
  -H "Authorization: Bearer sg_…" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"un faro al amanecer, en acuarela"}'

La respuesta trae un enlace a la imagen. El enlace dura 7 días: descarga la imagen si la vas a usar después.

Un programa sin navegador envía la clave en el encabezado Authorization, a la misma dirección:

Claude Code en un servidor

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

Cursor y otros programas

En Cursor, agrega esto al archivo ~/.cursor/mcp.json. Otros programas con MCP usan la misma dirección y el mismo encabezado.

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

Una skill es un archivo que le enseña al agente a usar SmartGenius: el orden de las llamadas, cómo esperar un post y qué no hacer nunca. El plugin ya la trae. En cualquier otro agente, instálala con un comando:

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

El archivo queda en ~/.agents/skills/smartgenius/, y Claude Code y Codex reciben un enlace a él. ¿Usas otro agente? Apúntalo a ese archivo. Para actualizarla, vuelve a ejecutar el comando.

Leer el script antesVer la skill

Son cinco operaciones. Por MCP, cada una es una herramienta. Por HTTP, cada una es una ruta. Las dos hacen lo mismo.

list_profilesGET /v1/profiles

Lista los perfiles del espacio. Todo post necesita la @ de uno de ellos.

create_postPOST /v1/profiles/{profile}/posts

Empieza un post a partir de una idea. Responde al instante, antes de que el post esté listo.

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

Muestra el post: en qué estado está, el texto de cada diapositiva, el pie de foto, los hashtags y el enlace para abrirlo en SmartGenius. Con wait (hasta 50 s), la respuesta espera a que el post esté listo.

generate_imagePOST /v1/images

Crea de 1 a 4 imágenes a partir de un prompt. Con profile, salen con el estilo y los colores de ese perfil.

get_usageGET /v1/usage

Cuántas imágenes se usaron y cuántas quedan este mes, el límite del día y cuándo se reinicia el mes.

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

Descarga el post terminado en un zip: un JPEG por diapositiva y el pie de foto en caption.txt.

create_post también acepta format (carousel, post o story), slides, objective, tone, cta y links (hasta 5 páginas para leer antes). generate_image acepta aspectRatio (1:1, 4:5, 9:16, 16:9 y otros) y count. El perfil funciona con o sin la @.

1. Llama a list_profiles y elige el perfil.
2. Llama a create_post con la @ del perfil y la idea. La respuesta trae el id del post.
3. Llama a get_post con wait=30 hasta que making.status sea done o failed. Un carrusel tarda unos minutos.
4. El post queda como borrador. Aprobar, programar y publicar sigue en manos de una persona, en el enlace studioUrl.

Llamar a create_post otra vez crea un segundo post y gasta las imágenes de nuevo. Para repetir una llamada sin ese riesgo (tras un error de red, por ejemplo), envía un requestId: cualquier texto tuyo, como un UUID. Con el mismo requestId recibes la respuesta de la primera llamada y no se gasta nada dos veces. Dura 24 horas y también sirve para generate_image.

curl https://api.smartgenius.app/v1/profiles/@tu.perfil/posts \
  -H "Authorization: Bearer sg_…" \
  -H "Content-Type: application/json" \
  -d '{"idea":"5 consejos para conservar el pan casero","requestId":"4b1d7e2a-9c3f-4e8b-a6d5-1f0e2c3b4a59"}'

• Cada imagen sale de la cuota mensual del espacio: una por diapositiva de un post, una por imagen suelta. Es la misma cuota de los posts que haces en SmartGenius, en cualquier plan. Una imagen que falla no se cobra.
• Cada clave hace hasta 120 llamadas por minuto.
• Cada clave puede tener hasta 5 esperas de get_post al mismo tiempo. A partir de la sexta, get_post responde al instante, sin esperar.
• generate_image crea de 1 a 4 imágenes por llamada.
• Los enlaces de las imágenes duran 7 días. Descarga lo que vayas a usar: después, la imagen se borra.

Por HTTP, un error llega así. Por MCP, llega el mismo objeto con isError: true: { error: { code, message, details } }

UNAUTHORIZED · INVALID_TOKEN

Falta la clave, fue revocada o quien la creó salió del espacio. Crea otra clave.

FORBIDDEN

Quien creó la clave no puede hacer eso en este espacio. Por ejemplo: quien solo aprueba posts no gasta imágenes.

NOT_FOUND

Ese perfil o ese post no está en este espacio. Revisa la @ con list_profiles.

VALIDATION_ERROR

Algún campo vino mal (details dice cuál y por qué), o el requestId ya se usó para un pedido distinto.

CONFLICT

La primera llamada con ese requestId todavía no respondió. Espera los segundos de retryAfterSecs y vuelve a llamar con el mismo requestId.

QUOTA_EXCEEDED

Se acabaron las imágenes del mes o del día. details.resetAt dice cuándo vuelven; un plan mayor o un paquete de imágenes lo libera antes.

RATE_LIMIT_EXCEEDED

Demasiadas llamadas en un minuto. Espera los segundos de retryAfterSecs y vuelve a intentarlo.

GENERATION_FAILED

El modelo de imagen falló o rechazó el pedido. No se cobró nada. Vuelve a intentarlo o cambia el prompt.