# Conectar tu agente por MCP

Claude Code, Codex, Cursor y apps de chat como claude.ai pueden usar Staglight como herramientas: estimar el precio, generar, consultar y descargar, con el mismo saldo que el estudio.

## Apps de chat en menos de un minuto

claude.ai, Claude Desktop y otras apps de chat con conectores personalizados inician sesión con tu cuenta de Staglight (OAuth 2.1), así que nadie tiene que pegar una clave. Apruebas cada app una vez y le das un tope de gasto.

### Claude

[Añadir a Claude](https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Staglight&connectorUrl=https%3A%2F%2Fstaglight.ai%2Fmcp)

1. Haz clic en el botón de arriba o, en Claude, abre Personalizar > Conectores > Añadir conector personalizado con el nombre Staglight y la URL `https://staglight.ai/mcp`.
2. Haz clic en Continuar, deja Iniciar sesión ahora y haz clic en Añadir; luego entra con tu cuenta de Staglight, elige qué puede hacer y su tope de gasto, y haz clic en Permitir. Con el plan gratuito puedes añadir un conector personalizado; en Team y Enterprise lo añade primero un propietario y tú haces clic en Conectar.
3. En un chat, abre + > Conectores y activa Staglight. Adjunta una foto del producto y pide: hazme un anuncio para este producto.

### ChatGPT

1. En ChatGPT en la web, abre Ajustes > Plugins y haz clic en + > Añadir servidor MCP personalizado. Hace falta un espacio Business, Enterprise o Edu que lo permita; en Pro solo puede leer.
2. Llámalo Staglight, pega la URL `https://staglight.ai/mcp`, elige OAuth, marca la casilla para continuar y haz clic en Crear como plugin.
3. Inicia sesión con tu cuenta de Staglight y haz clic en Permitir.
4. En un chat nuevo, escribe @, elige Staglight y pide tu anuncio.

> Cada conexión aparece en [Ajustes > Conexiones](https://staglight.ai/app/ajustes#conexiones) con su tope de gasto (en 24 horas); Desconectar le quita el acceso al instante. Las herramientas que gastan, suben o cambian algo necesitan el permiso Crear anuncios y gastar créditos; una conexión de solo lectura puede ver pero no gastar.

## Servidor

- URL: `https://staglight.ai/mcp`
- Transporte: `Streamable HTTP`
- Autenticación: `OAuth 2.1 · Bearer <key>`
- Protocolo: `2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26`

Crea una clave con límite diario en [el estudio](https://staglight.ai/app/api) y guárdala como `STAGLIGHT_API_KEY`.

Terminal:

```bash
export STAGLIGHT_API_KEY="sl_live_..."
```

## Claude Code

Un solo comando para todos los proyectos de este equipo. La terminal inserta la clave y Claude Code la guarda en `~/.claude.json`.

Terminal:

```bash
claude mcp add --transport http staglight https://staglight.ai/mcp \
  --header "Authorization: Bearer $STAGLIGHT_API_KEY" --scope user
```

> ¿Prefieres iniciar sesión en vez de usar una clave? Ejecuta el comando sin la parte `--header`, escribe `/mcp` en Claude Code y elige staglight para iniciar sesión con tu cuenta de Staglight.

Comprueba que se conectó:

Terminal:

```bash
claude mcp get staglight
```

Para compartirlo con un equipo en el repositorio, añade `.mcp.json`. Cada persona guarda la clave en su propia `STAGLIGHT_API_KEY`.

.mcp.json:

```json
{
  "mcpServers": {
    "staglight": {
      "type": "http",
      "url": "https://staglight.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${STAGLIGHT_API_KEY}"
      },
      "timeout": 600000
    }
  }
}
```

> Llama a la variable `STAGLIGHT_API_KEY`. Claude Code deja vacías en los encabezados remotos algunas variables de credenciales con nombres reservados, así que usa esta.

## Codex

Terminal:

```bash
codex mcp add staglight --url https://staglight.ai/mcp --bearer-token-env-var STAGLIGHT_API_KEY
```

O escríbelo a mano en la configuración de Codex:

~/.codex/config.toml:

```toml
[mcp_servers.staglight]
url = "https://staglight.ai/mcp"
bearer_token_env_var = "STAGLIGHT_API_KEY"
startup_timeout_sec = 20
tool_timeout_sec = 120
```

> Codex corta una llamada a una herramienta a los 60 s por defecto. Todas las herramientas responden en menos de 50 s, y `get_job` espera 50 s como máximo.

## Cursor

En `~/.cursor/mcp.json` para todos los proyectos, o en `.cursor/mcp.json` para uno:

~/.cursor/mcp.json:

```json
{
  "mcpServers": {
    "staglight": {
      "url": "https://staglight.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${env:STAGLIGHT_API_KEY}"
      }
    }
  }
}
```

## Claude Desktop y claude.ai

claude.ai y Claude Desktop se conectan iniciando sesión con tu cuenta de Staglight: consulta [Apps de chat](#chat-apps).

Si prefieres usar ahí una clave de API, usa como puente en tu equipo el paquete de la comunidad `mcp-remote` en `claude_desktop_config.json`:

claude_desktop_config.json:

```json
{
  "mcpServers": {
    "staglight": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://staglight.ai/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}",
        "--transport",
        "http-only"
      ],
      "env": {
        "AUTH_HEADER": "Bearer sl_live_..."
      }
    }
  }
}
```

> `mcp-remote` es un paquete de terceros que se ejecuta en tu equipo con tu clave. Revísalo antes de usarlo.

## Herramientas

Las herramientas de pago aceptan `max_credits` e `idempotency_key`. Cada resultado trae un texto breve, los datos en JSON y, para archivos terminados, enlaces de descarga.

| Herramienta | Qué hace | Precio |
|---|---|---|
| get_balance | Saldo, límite diario de la clave y lo que queda hoy. | Gratis |
| buy_credits_link | Enlace para comprar créditos en el estudio. | Gratis |
| list_models | Modelos y herramientas con sus campos y precio inicial. | Gratis |
| estimate_cost | Precio exacto de una llamada antes de hacerla. | Gratis |
| upload_from_url | Importa un archivo desde un enlace directo y devuelve su id. | Gratis |
| upload_file | Guarda una foto o un clip corto que adjuntas en el chat (base64, hasta 12 MB) y devuelve su id. | Gratis |
| upload_image | Lo mismo que upload_file. | Gratis |
| list_media | Subidas y resultados con enlaces firmados. | Gratis |
| generate_image | Imágenes de producto con Nano Banana, GPT Image, Seedream o Flux. | De pago |
| generate_video | Clips con Kling, Veo, Seedance, Hailuo o Wan, además de avatares y control de movimiento. | De pago |
| generate_voice | Voz en off con ElevenLabs. Si falla, se reintenta una vez con una voz de respaldo parecida sin cobro extra (sin tiempos por palabra); envía allow_fallback: false para recibir el reembolso en su lugar. | De pago |
| generate_music | Música de fondo con Suno. | De pago |
| upscale | Aumenta la resolución de una imagen o un video. | De pago |
| remove_background | Recorta el producto (PNG transparente). | De pago |
| add_captions | Incrusta en el video subtítulos sincronizados palabra por palabra. | De pago |
| reburn_captions | Vuelve a incrustar los subtítulos con líneas editadas o un estilo nuevo, sin transcribir otra vez. Gratis, con un límite diario. | De pago |
| merge_videos | Une clips en un solo video con una única relación de aspecto. | De pago |
| clean_export | Copia sin datos de ubicación, dispositivo, edición ni modelo de IA; mantiene una nota de contenido con IA salvo que la desactives. | De pago |
| analyze_ad | Evalúa un anuncio desde un archivo o un enlace de publicación y escribe nuevos ganchos y un guion para rehacerlo con tu producto. | De pago |
| create_job | Ejecuta cualquier op de list_models. | De pago |
| social_download | Descarga una publicación de TikTok, Instagram, Facebook o Shorts en tu biblioteca. Gratis, con un límite diario. | De pago |
| list_characters | Lista tus personajes guardados con sus fotos y su voz, y el precio de una hoja de personaje. | Gratis |
| get_character | Un personaje guardado con sus fotos y su voz. | Gratis |
| create_character | Guarda una persona una sola vez (nombre, de 1 a 3 fotos, voz opcional) para usarla en las escenas de Script Runner. Requiere confirmar el derecho de imagen. | Gratis |
| update_character | Cambia el nombre, la descripción, las fotos o la voz de un personaje. | Gratis |
| delete_character | Borra un personaje guardado. | Gratis |
| make_character_sheet | Dibuja de frente, de perfil y en primer plano a una persona a partir de una foto. De pago, se cobra una vez. | De pago |
| parse_script | Lee un guion y muestra cada escena con su reparto, modelo, duración y precio. Gratis. | Gratis |
| edit_scenes | Edita, quita, recupera o añade escenas de Script Runner antes de crear los clips. | De pago |
| get_job | Estado y resultados, espera hasta 50 s. | Gratis |
| list_jobs | Trabajos, también filtrados por idempotency_key si se agotó el tiempo de espera o por ejecución del Estudio de anuncios. | Gratis |
| cancel_job | Cancela un trabajo que no ha empezado (reembolsado). | Gratis |
| list_formats | Formatos de anuncio con precio por calidad. | Gratis |
| list_products | Productos guardados para usar en anuncios. | Gratis |
| create_product | Guarda un producto con su nombre y de 1 a 8 fotos, para usarlo en todos tus anuncios. | Gratis |
| get_product | Un producto guardado con los enlaces de sus fotos. | Gratis |
| create_ad | Empieza un anuncio completo a partir de un formato. Con auto llega al final dentro de max_credits. | De pago |
| propose_ad | Propone formato y precio a partir de una descripción escrita. | De pago |
| create_ad_from_brief | Propone y empieza el anuncio en una sola llamada. Con auto lo termina solo dentro de max_credits. | De pago |
| get_ad | Estado de un anuncio en curso, espera hasta 50 s. | Gratis |
| approve_ad_step | Aprueba un paso de revisión y pone en marcha los siguientes, o deja el resto en modo auto. | De pago |
| redo_ad_step | Toma nueva de un elemento (se cobra otra vez). | De pago |
| motion_remix | Una versión nueva de tu propio clip por personaje, producto o estilo: borradores, eliges, terminas. El modo reemplazar y una persona o cara como target piden likeness: true (desde el 31-10-2026); el cambio preciso se detiene en el paso mask para que lo revises. | De pago |
| cancel_ad | Detiene un anuncio y reembolsa los trabajos que no han empezado. | Gratis |
| studio_list | Los estudios del Estudio de anuncios con sus tipos, campos y precios. | Gratis |
| studio_estimate | Precio exacto de un clic en el Estudio de anuncios, con tu saldo. Gratis. | Gratis |
| studio_check | Hace las comprobaciones gratuitas de un estudio antes de pagar (Shorts de ranking: cada nivel y la variedad entre ellos). | Gratis |
| studio_run | Crea imágenes del Estudio de anuncios: se cobra un trabajo por imagen y se reembolsa si falla. | De pago |
| studio_helper | Ejecuta un asistente del Estudio de anuncios (un precio fijo pequeño, míralo en studio_list). link_scan lee la página de un producto y devuelve sus fotos como tus archivos subidos, el nombre y una línea de descripción. | De pago |
| studio_series | La serie de un canal o el proyecto de una tienda: lo que recuerda y sus episodios. | Gratis |
| studio_series_save | Empieza o cambia una serie: sus notas, lo que pidió la audiencia o volver a un episodio anterior. | Gratis |
| ad_series | La serie o el proyecto de un formato: lo que recuerda y sus tomas. | Gratis |
| ad_series_save | Empieza o cambia la serie de un formato: sus notas, lo que pidió tu audiencia o volver a una toma anterior. | Gratis |
| studio_get_run | Estado de un clic en el Estudio de anuncios: cada trabajo (incluidos los pasos posteriores) y los archivos terminados. | Gratis |

## Reglas de gasto para agentes

- Llama a `estimate_cost` antes de cualquier herramienta de pago. Es gratis y calcula el precio de la llamada exacta: `tool` más `arguments`.
- Envía `max_credits` y un `idempotency_key` nuevo en cada llamada de pago.
- Las herramientas de pago responden al momento con un `job_id` o `run_id`. Consulta `get_job` o `get_ad` con `wait_seconds=50`.
- Si se agota el tiempo de espera, llama a `list_jobs` con el mismo `idempotency_key` antes de volver a pagar.
- Los trabajos fallidos se reembolsan solos. Sin créditos, `buy_credits_link` da al usuario un enlace al estudio. Ningún pago pasa por el MCP.
- Da a cada agente su propia clave con límite diario. Al llegar al límite recibe `daily_limit_reached` y se detiene.
- Con `auto: true`, `create_ad` y `create_ad_from_brief` aprueban solos cada paso de revisión mientras todo el anuncio quepa en `max_credits`. Si el siguiente paso lo superara, el anuncio espera en ese paso con `auto_stopped` y no se cobra nada más.

## Errores

Los errores de las herramientas llegan como resultado con `isError: true` y los mismos códigos que la API REST. Sin créditos incluye `needed`, `balance` y `topup_url`. Una clave que falta o es incorrecta da HTTP 401 con `WWW-Authenticate`.

JSON:

```json
{
  "content": [
    {
      "type": "text",
      "text": "Error insufficient_credits: This needs 63 credits and the balance is 10. ..."
    }
  ],
  "structuredContent": {
    "error": {
      "code": "insufficient_credits",
      "message": "This needs 63 credits and the balance is 10. Buy credits to continue.",
      "status": 402,
      "needed": 63,
      "balance": 10,
      "charged": false,
      "topup_url": "https://staglight.ai/app/creditos?need=53"
    }
  },
  "isError": true
}
```

## Prueba con curl

El servidor responde JSON normal por POST, sin sesiones, así que curl funciona:

Terminal:

```bash
curl -s https://staglight.ai/mcp \
  -H "Authorization: Bearer $STAGLIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-11-25", "capabilities": {}, "clientInfo": {"name": "curl", "version": "1.0"}}}'
```

Terminal:

```bash
curl -s https://staglight.ai/mcp \
  -H "Authorization: Bearer $STAGLIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "get_balance", "arguments": {}}}'
```