Suntropy Connect para agentes de IA: alta sin contraseña, inversores conectados y monitorización

Guía para agentes (Claude, ChatGPT, Codex, Cursor, Claude Code o el tuyo propio) cuyo usuario quiere saber cómo van sus plantas fotovoltaicas, qué alarmas tienen sus inversores o por qué una planta no produce. Puedes dar de alta al usuario en Suntropy Connect sin contraseña, pedirle que conecte sus cuentas de fabricantes sin ver sus credenciales y leer su monitorización por MCP, por HTTP o con la CLI. El usuario sólo interviene para darte su correo, dictarte un código de 6 dígitos y conectar su cuenta del fabricante en un enlace.

Qué puedes hacer

Suntropy Connect lee las plataformas de monitorización de los fabricantes de inversores con su API oficial y lo devuelve todo normalizado en kW y kWh:

• Plantas: lista, estado en tiempo real, energía de hoy y del mes, resumen de todas las cuentas a la vez.
• Energía: producción, consumo, red y batería, de 5 minutos a años.
• Equipos: inversores, contadores y baterías, con lecturas cada 5 minutos (tensiones, frecuencia, strings, estado).
• Alarmas: abiertas y cerradas, con causa y recomendación del fabricante, y vigilancia periódica con leídas y no leídas.

Es sólo lectura: nunca cambia nada en un inversor ni en el portal del fabricante.

Lo que necesitas del usuario

No hace falta que el usuario cree una contraseña: si un día quiere entrar en la app, usa «He olvidado mi contraseña» en https://app.suntropy.ai.

Elige la vía

• Tu cliente admite conectores MCP remotos con OAuth (Claude, ChatGPT, Cursor, Claude Code, Codex): añade el conector (sección 6). El cliente abre el login de Suntropy y el usuario aprueba; si no tiene cuenta, la crea en esa misma pantalla. Después pasa a la sección 4.
• Corres en una terminal: usa la CLI de Suntropy (sección 3), disponible desde la versión 0.19.0.
• Cualquier otro caso, o si la CLI no está a tu alcance: HTTP directo contra el gateway (secciones 1, 4 y 5). Funciona hoy y es lo que usa la CLI por debajo.

Gateway: https://connect-gateway.suntropy.ai · metadata OAuth: https://connect-gateway.suntropy.ai/.well-known/oauth-authorization-server

1 · Alta o inicio de sesión por HTTP (código por correo)

Es el flujo de dispositivo de OAuth (RFC 8628) más un código por correo. Sirve igual para cuentas nuevas y para cuentas que ya existen, y la respuesta no revela si el correo tenía cuenta. Usa client_id suntropy-cli (público) o el tuyo, si te registraste por DCR.

1.1 Pide un código de dispositivo.

curl -s -X POST https://connect-gateway.suntropy.ai/device_authorization \
  -H 'Content-Type: application/json' -d '{"client_id":"suntropy-cli"}'
# → {"device_code":"…","user_code":"ABCD-EFGH","verification_uri":"https://app.suntropy.ai/authorize-connector",
#    "verification_uri_complete":"https://app.suntropy.ai/authorize-connector?user_code=ABCD-EFGH&…","expires_in":1800,"interval":5}

Guarda device_code (no se lo enseñes al usuario) y user_code. Vale 30 minutos.

1.2 Manda el código al correo del usuario, con las UTM de la página donde nos encontraste:

curl -s -X POST https://connect-gateway.suntropy.ai/device_authorization/email \
  -H 'Content-Type: application/json' \
  -d '{"device_code":"<device_code>","client_id":"suntropy-cli","email":"<correo del usuario>",
       "utm_source":"ia-agente","utm_medium":"mcp","utm_campaign":"connect-agentes","utm_content":"connect-agentes"}'
# → 202 {"sent":true,"expires_in":900}

• utm_source es ia-agente y utm_medium es cli o mcp (si no los mandas, el gateway pone esos). En utm_campaign y utm_content pon el slug de la página o del artículo que te trajo aquí; por ejemplo alarma-2034-grid-overvoltage-huawei. Quedan en el alta del usuario.
• Dile al usuario: «Te ha llegado un correo de Suntropy con un código de 6 dígitos. Dímelo, o pulsa "Aprobar acceso" en el correo». El correo muestra también el user_code para que pueda cotejarlo.

1.3 Verifica el código que te dicta.

curl -s -X POST https://connect-gateway.suntropy.ai/device_authorization/email/verify \
  -H 'Content-Type: application/json' \
  -d '{"device_code":"<device_code>","client_id":"suntropy-cli","code":"482913"}'
# → 200 {"approved":true,"trial":{"started":true,"endsAt":"…","days":7}}   (trial sólo si se acaba de empezar la prueba)

1.4 Canjea el token. Si el usuario pulsó el botón del correo en vez de dictarte el código, salta directamente aquí y sondea cada interval segundos:

curl -s -X POST https://connect-gateway.suntropy.ai/token \
  -d grant_type=urn:ietf:params:oauth:grant-type:device_code \
  -d client_id=suntropy-cli --data-urlencode device_code=<device_code>
# → {"access_token":"pvo_…","refresh_token":"…","token_type":"Bearer","expires_in":…}

Mientras no esté aprobado responde authorization_pending; slow_down significa que alargues el intervalo; access_denied, que el usuario lo ha denegado; expired_token, que hay que empezar de nuevo. Renueva con grant_type=refresh_token. Guarda los tokens como secretos y no los escribas en el chat.

Errores del código por correo

Sin correo: login por enlace. Da al usuario verification_uri_complete (o verification_uri y el user_code) para que lo abra en el navegador, entre o se dé de alta y apruebe. Tú sondeas /token como en 1.4.

2 · Qué hacer con el 402 licence_inactive

Lo devuelve /device_authorization/email/verify cuando la cuenta ya existía y no tiene licencia de Suntropy Connect ni puede empezar la prueba sola:

{"error":"licence_inactive","error_description":"…","licence":{…},"trialEligible":true,
 "verification_uri_complete":"https://app.suntropy.ai/authorize-connector?user_code=…"}

• Dale al usuario verification_uri_complete. Si trialEligible es true, ahí puede empezar la prueba de 7 días con un clic y aprobarte; si es false, ahí ve las opciones de su licencia.
• El device_code sigue vivo: sondea /token (1.4) hasta que lo apruebe. No le pidas datos de pago en el chat.

3 · Con la CLI de Suntropy (desde la versión 0.19.0)

suntropy connect hace todo lo anterior y guarda la sesión. Los comandos de Connect llegan a npm con la versión 0.19.0: comprueba la versión antes de usarlos y, si suntropy connect --help no existe en la que tienes, usa la vía HTTP.

npx -y @enerlence/suntropy-cli@latest --version       # tiene que ser 0.19.0 o superior
npx -y @enerlence/suntropy-cli@latest connect status

# Alta o login por correo (si el correo no tiene cuenta, se crea)
npx -y @enerlence/suntropy-cli@latest connect login --email <correo> --utm-campaign <slug-de-la-pagina>
npx -y @enerlence/suntropy-cli@latest connect login --code 482913
# si el usuario pulsó «Aprobar acceso» en el correo, o tras resolver el 402 en el navegador:
npx -y @enerlence/suntropy-cli@latest connect login --continue

# Por enlace, sin correo
npx -y @enerlence/suntropy-cli@latest connect login --no-wait   # devuelve verificationUriComplete
npx -y @enerlence/suntropy-cli@latest connect login --continue

Sin terminal interactiva, los comandos no se quedan esperando: devuelven el siguiente paso en el campo next. La salida es JSON y los errores llevan un code estable. Con la CLI instalada (npm install -g @enerlence/suntropy-cli), el comando es simplemente suntropy.

Lecturas y conexiones con la CLI:

suntropy connect summary                         # empieza aquí
suntropy connect plants --query "<nombre o dirección>"
suntropy connect plant-status <plantId> <plantId>
suntropy connect energy <plantId> --metric pv_yield --granularity day --from 2026-11-01
suntropy connect alarms --min-severity major --unread-only
suntropy connect alarms watch set --enabled true --provider all
suntropy connect add huawei --wait               # enlace para que el usuario conecte su cuenta
suntropy connect tools                           # todas las herramientas del MCP

Skill para tu agente, con el flujo completo y sus trampas: https://github.com/enerlence/suntropy-cli-skills/blob/main/skills/connect-monitoring.md (se instala como las demás skills del repo, por ejemplo en ~/.claude/skills/ o .agents/skills/).

4 · Conectar las cuentas de los fabricantes

Por enlace (recomendado). El usuario introduce sus credenciales en Suntropy, no en el chat:

• MCP: create_connection_link con {"provider":"huawei"}.
• HTTP: POST https://connect-gateway.suntropy.ai/integrations/connection-links con Authorization: Bearer <access_token> y {"provider":"huawei","label":"<nombre opcional>"} → 201 {id, provider, url, expiresAt, authorizeUrl?}.

Dale la url al usuario: es de un solo uso, caduca en 15 minutos y abre el formulario de esa marca ya elegido. En Sungrow y Enphase (enlighten) llega además authorizeUrl, que le lleva directo a la pantalla de consentimiento del fabricante. Después comprueba con list_connections (o GET /integrations/connection-links/{id}: pending, done o expired) hasta que aparezca la cuenta.

Ids de marca: huawei, deye, goodwe, solis, sungrow, enlighten (Enphase autorizado en la web de Enphase), enphase (Enphase con la aplicación Partner propia del instalador), growatt y fronius. Qué pide cada una y dónde lo encuentra el usuario: get_connection_catalog (o GET /integrations/catalog). No contiene valores de nadie.

Directa (sólo si el usuario lo pide). create_connection con {provider, fields} añade la cuenta con los valores que el usuario te dé. Las credenciales pasan por tu contexto: ofrécela sólo si el usuario prefiere dártelas, nunca las repitas ni las guardes. Suntropy prueba el acceso con el fabricante antes de guardar. Las marcas que se autorizan en la web del fabricante (howToConnect: link_only: Sungrow y enlighten) no se pueden añadir así. Borrar una cuenta sólo lo puede hacer el usuario, en Suntropy.

5 · Leer plantas y alarmas

MCP de todas las marcas: https://connect-gateway.suntropy.ai/monitoring/mcp. Hay uno por marca con las mismas herramientas: /huawei/mcp, /deye/mcp, /goodwe/mcp, /solis/mcp, /sungrow/mcp, /enphase/mcp, /growatt/mcp y /fronius/mcp.

Sin cliente MCP, llama a las herramientas por HTTP (JSON-RPC sobre Streamable HTTP):

curl -s -X POST https://connect-gateway.suntropy.ai/monitoring/mcp \
  -H "Authorization: Bearer $SUNTROPY_CONNECT_TOKEN" \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_monitoring_summary","arguments":{}}}'

Cómo leer bien:

• Pide muchas plantas o equipos en una sola llamada y no repitas la misma pregunta: los fabricantes racionan su API por cuenta y las respuestas llevan freshness.ageSeconds. Un error de cuota dice cuándo reintentar: no hagas bucles.
• Si una cuenta falla, las demás responden y el fallo viene en issues: cuéntaselo al usuario en vez de concluir que no tiene plantas.
• Una planta «sana» puede tener el inversor parado: contrasta el estado con la energía del día.
• Sin vigilancia de alarmas sólo ves las abiertas en ese momento. Si el usuario quiere un histórico, propón set_alarm_watch.
• Diagnóstico paso a paso, con un caso real y una tabla de interpretación: https://www.suntropy.ai/blog/diagnostico-incidencia-inversor-fotovoltaico/index.md

6 · Añadir el MCP a cada cliente

URL: https://connect-gateway.suntropy.ai/monitoring/mcp (o la de una marca). Autenticación OAuth: el cliente abre el login de Suntropy, el usuario entra o se da de alta y aprueba.

Con la CLI 0.19.0 o superior, suntropy mcp add --client claude-code|codex|cursor|claude-ai|chatgpt hace lo mismo (con --print sólo enseña el comando; con --brand huawei, el MCP de una marca).

Reglas

• El alta la decide el usuario. Pregúntale antes de usar su correo. El código de 6 dígitos sólo se lo mandas al gateway: no lo guardes ni lo repitas.
• Nunca pidas la contraseña de Suntropy. Las credenciales del fabricante, sólo por enlace, salvo que el usuario elija la vía directa.
• Sólo lectura: no prometas que Suntropy cambie la configuración de un inversor.
• Fronius cobra su API: no la presentes como gratuita. Growatt limita mucho las consultas: los datos pueden tener horas.
• Todo queda acotado a la cuenta del usuario: no ves plantas de otras empresas.
• Atribución: manda siempre utm_source=ia-agente, utm_medium=cli|mcp y el slug de la página de origen en utm_campaign/utm_content.

Contacto

hola@suntropy.ai · https://connect.suntropy.ai · Para personas: crear cuenta en https://app.suntropy.ai/signup?utm_source=ia-agente&utm_medium=ia&utm_campaign=connect-agentes