# 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.

| Marca | Estado | Qué tiene que hacer el usuario |
|---|---|---|
| Huawei FusionSolar | disponible | Crear una cuenta API (Northbound), no vale el usuario web. Guía: https://www.suntropy.ai/blog/cuenta-api-fusionsolar-northbound/index.md |
| Deye Cloud | beta | Usuario y contraseña de Deye Cloud y el centro de datos |
| GoodWe SEMS | beta | Usuario del portal SEMS+ |
| SolisCloud | beta | Pedir a Solis que active la API y copiar Key ID y Key Secret |
| Sungrow iSolarCloud | beta | Autorizar en la web de Sungrow las plantas que quiera compartir (OAuth) |
| Enphase Enlighten | beta | Autorizar en la web de Enphase (OAuth) o usar su propia aplicación Partner |
| Growatt ShineServer | beta | Un token de la API de Growatt y el servidor de su cuenta. Growatt raciona mucho su API: Suntropy guarda los datos para no gastar las consultas |
| Fronius Solar.web | beta | Acceso a la Solar.web Query API, **un servicio de pago que contrata con Fronius** y que Fronius factura por puntos de datos leídos. Díselo antes de que lo pida |

## Lo que necesitas del usuario

| Paso | Quién | Qué |
|---|---|---|
| Permiso para usar su correo | **Usuario** | Pregúntale si quiere que le des de alta (o le identifiques) en Suntropy con su correo |
| Código de 6 dígitos | **Usuario**, 1 minuto | Le llega por correo; te lo dicta o pulsa «Aprobar acceso» en el mismo correo |
| Licencia de Connect | Automática en cuentas nuevas | Una cuenta nueva empieza sola la prueba de 7 días. Si ya la gastó, la resuelve él en el navegador (ver «Qué hacer con el 402») |
| Cuenta del fabricante | **Usuario**, en Suntropy | Le das un enlace de un solo uso y la conecta él; tú no ves sus credenciales |

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.**

```bash
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:

```bash
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.**

```bash
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:

```bash
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**

| Respuesta | Qué hacer |
|---|---|
| 400 `invalid_email` | Comprueba el correo con el usuario (también salta con dominios desechables) |
| 400 `invalid_code` con `attempts_left` | Pídele que lo revise; no lo inventes ni lo pruebes a ciegas |
| 410 `expired_token` | El código del correo caducó (15 minutos): vuelve a 1.2 |
| 429 `too_many_attempts` o `slow_down` | Espera; no reintentes en bucle |
| 409 `already_decided` | Se aprobó o denegó en la web mientras tanto: ve a 1.4 |
| 402 `licence_inactive` | Ver la sección 2 |

**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:

```json
{"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.

```bash
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:

```bash
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`.

| Para qué | Herramientas |
|---|---|
| Cuentas conectadas | `list_connections` (estado, último error y qué hacer), `create_connection_link`, `get_connection_catalog`, `create_connection` |
| Visión general | `get_monitoring_summary` (empieza aquí: plantas sanas, en fallo y desconectadas por cuenta, con la energía de hoy y del mes) |
| Plantas | `list_plants`, `get_plant_status`, `get_plant_energy` (una métrica por llamada), `get_plant_power_curve` |
| Equipos | `list_devices`, `get_device_realtime`, `get_device_history` (5 minutos, un día por llamada), `get_device_settings` |
| Alarmas | `list_alarms`, `get_alarm_watch`, `set_alarm_watch`, `poll_alarms`, `mark_alarms_read`, `silence_alarm_reviews`, `lift_alarm_silence` |

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

```bash
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.

| Cliente | Cómo |
|---|---|
| Claude Code | `claude mcp add --transport http --scope user suntropy-connect https://connect-gateway.suntropy.ai/monitoring/mcp`; después, `/mcp` y autenticar |
| Codex | `codex mcp add suntropy-connect --url https://connect-gateway.suntropy.ai/monitoring/mcp` y `codex mcp login suntropy-connect` |
| Cursor | En `~/.cursor/mcp.json`: `{"mcpServers":{"suntropy-connect":{"url":"https://connect-gateway.suntropy.ai/monitoring/mcp"}}}`; después, Settings › MCP › «Needs login» |
| Claude (web, escritorio y móvil) | Ajustes › Conectores › Añadir conector personalizado, con la URL. Enlace con el diálogo relleno: https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Suntropy%20Connect&connectorUrl=https%3A%2F%2Fconnect-gateway.suntropy.ai%2Fmonitoring%2Fmcp |
| ChatGPT | Con el modo desarrollador activado en los ajustes de conectores, crea un conector con la URL y autenticación OAuth |

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