MCP e agenti AI

Usalo con gli agenti IA#

Usa Server MCP quando vuoi che un assistente crei contenuti multimediali per te, per esempio nelle chat di Claude Code o Cursor. Usa Agent Skill quando un agente scrive codice per l’API. Puoi usare entrambi: lo skill indica anche agli agenti di preferire gli strumenti MCP quando sono connessi.

URL del server e accesso#

• Trasporto: Streamable HTTP senza stato. È compatibile con client basati sulle versioni del protocollo MCP 2025 e 2026-07-28.
• Accesso: OAuth 2.1, secondo la specifica di autorizzazione MCP. Alla prima connessione, il client apre nel browser una pagina CheaperGen. Accedi e approva l’app. Le app approvate sono elencate in Dashboard → Chiavi API → App collegate, dove puoi scollegarle in qualsiasi momento.
• Uso senza browser e CI: invia invece una chiave API, come Authorization: Bearer cg_live_…. Consulta Usa una chiave API.

Collega un client#

Claude (claude.ai e Claude Desktop)#

1. Apri Personalizza → Connettori e aggiungi un connettore personalizzato.
2. Assegna il nome CheaperGen, incolla l’URL qui sopra e scegli Aggiungi.
3. Scegli Collega, accedi a CheaperGen e approva. Poi attiva il connettore in una chat dal menu degli strumenti.

Con i piani Team ed Enterprise, potrebbe essere necessario che un proprietario aggiunga prima il connettore per l'organizzazione. I connettori aggiunti su claude.ai compaiono anche in Claude Desktop.

Claude Code#

claude mcp add --transport http cheapergen https://cheapergen.com/api/mcp

Poi esegui /mcp, seleziona cheapergen e scegli Autentica (oppure esegui claude mcp login cheapergen in un terminale). Il browser si apre per accedere e approvare. Aggiungi --scope user per usarlo in tutti i progetti. In alternativa, installa il plugin, che aggiunge il server e Agent Skill in un solo passaggio:

/plugin marketplace add CheaperGen/skills
/plugin install cheapergen@cheapergen

ChatGPT#

App desktop (macOS e Windows). In modalità Work o Codex, l’app desktop ChatGPT usa le stesse impostazioni MCP di Codex CLI, quindi anche codex mcp add la collega. Oppure aggiungila direttamente nell’app:

1. Apri Settings → MCP servers → Add server.
2. Assegna il nome cheapergen, scegli Streamable HTTP, incolla l’URL qui sopra e salva.
3. Seleziona Riavvia, poi Autentica e accedi a CheaperGen per approvare. Digita /mcp nel campo di composizione per verificare la connessione.

chatgpt.com. I server MCP personalizzati diventano plugin, disponibili negli spazi di lavoro ChatGPT Business, Enterprise ed Edu (negli spazi Business li aggiungono amministratori e proprietari). Aggiungili dal web, non dall’app mobile:

1. Apri Plugins → + → Add custom MCP server.
2. Assegna il nome CheaperGen, incolla l’URL qui sopra e scegli OAuth come metodo di autenticazione.
3. Seleziona Ho capito e voglio continuare, scegli Crea come plugin, poi installalo, accedi e approva.
4. In una chat, digita @ e seleziona il plugin. ChatGPT chiede conferma prima di eseguire generate o add_credits.

Codex#

codex mcp add cheapergen --url https://cheapergen.com/api/mcp

Aggiunge il server a ~/.codex/config.toml e apre subito il browser per accedere. Hai saltato questo passaggio? Esegui codex mcp login cheapergen. Codex CLI, l’estensione IDE di Codex (menu a ingranaggio → Server MCP) e l’app desktop ChatGPT leggono tutti questo file, quindi basta configurarlo una volta. Le attività cloud di Codex non leggono questo file. Per modificarlo manualmente:

[mcp_servers.cheapergen]
url = "https://cheapergen.com/api/mcp"

Cursor#

Aggiungi questa configurazione a ~/.cursor/mcp.json (tutti i progetti) o a .cursor/mcp.json (un solo progetto). Poi apri Personalizza → MCP e collega cheapergen. Nel terminale di Cursor, esegui cursor-agent mcp enable cheapergen, poi cursor-agent mcp login cheapergen.

{
  "mcpServers": {
    "cheapergen": {
      "url": "https://cheapergen.com/api/mcp"
    }
  }
}

VS Code (GitHub Copilot)#

Aggiungi questa configurazione a .vscode/mcp.json, oppure esegui MCP: Add Server… e scegli HTTP. VS Code ti chiede di accedere al primo avvio del server. Poi usa gli strumenti nella modalità agente di Copilot Chat.

{
  "servers": {
    "cheapergen": {
      "type": "http",
      "url": "https://cheapergen.com/api/mcp"
    }
  }
}

Altri client#

I client che supportano server remoti e OAuth hanno bisogno solo dell’URL (alcuni usano "serverUrl" invece di "url"). I client che eseguono solo server locali (stdio) possono usare il bridge mcp-remote, che richiede Node.js e gestisce l’accesso.

{
  "mcpServers": {
    "cheapergen": {
      "type": "http",
      "url": "https://cheapergen.com/api/mcp"
    }
  }
}

{
  "mcpServers": {
    "cheapergen": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://cheapergen.com/api/mcp"
      ]
    }
  }
}

Usa una chiave API (senza browser, CI)#

Se non è possibile accedere tramite browser, invia una chiave API da Dashboard → Chiavi API. Crea una chiave diversa per ogni agente, così puoi revocarla singolarmente. Conservala in una variabile d’ambiente, come nell’esempio: gli apici singoli racchiudono il nome della variabile, non la chiave; il client ne legge il valore quando si connette. Claude Code espande anche ${CHEAPERGEN_API_KEY} nel file .mcp.json condiviso nell’ambiente di ciascuno sviluppatore.

claude mcp add --transport http cheapergen https://cheapergen.com/api/mcp \
  --header 'Authorization: Bearer ${CHEAPERGEN_API_KEY}'

codex mcp add cheapergen --url https://cheapergen.com/api/mcp \
  --bearer-token-env-var CHEAPERGEN_API_KEY

gemini mcp add --transport http cheapergen https://cheapergen.com/api/mcp \
  -H 'Authorization: Bearer ${CHEAPERGEN_API_KEY}'

{
  "mcpServers": {
    "cheapergen": {
      "type": "http",
      "url": "https://cheapergen.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${CHEAPERGEN_API_KEY}"
      }
    }
  }
}

npx @modelcontextprotocol/inspector --cli https://cheapergen.com/api/mcp --transport http \
  --header "Authorization: Bearer $CHEAPERGEN_API_KEY" --method tools/list

Strumenti#

Ogni strumento usa lo stesso codice dell’API REST (Riferimento API), quindi prezzi, convalida ed errori coincidono. I risultati sono in JSON compatto. Un’immagine completata arriva anche come piccola anteprima incorporata, così la chat la mostra e l’agente può controllarla, e ogni file di output come link a una risorsa da mostrare o scaricare.

Le immagini di solito vengono generate con una sola chiamata a generate. I video richiedono da uno a diversi minuti: l’agente invia il job, poi chiama get_generation con wait_seconds finché non termina. Un generate completato restituisce:

{
  "id": "gen_8c2QmX1nq0k4Lw7Z",
  "status": "succeeded",
  "endpoint": "bytedance/seedream-5.0-lite/text-to-image",
  "outputs": [
    "https://cdn.cheapergen.com/outputs/gen_8c2QmX1nq0k4Lw7Z.png"
  ],
  "cost": {
    "amount_usd": 0.0303,
    "official_usd": 0.035,
    "list_price_source": "official",
    "list_price_label": "Ufficiale",
    "saved_usd": 0.0047,
    "final": true
  },
  "created_at": "2026-10-16T09:12:43.545Z",
  "completed_at": "2026-10-16T09:12:49.058Z",
  "outputs_expire_at": "2026-10-17T09:12:49.058Z",
  "next": "Fatto. Mostra o scarica gli URL dei risultati prima che outputs_expire_at."
}

Prompt di esempio#

• “Quali modelli video di CheaperGen accettano video di riferimento e quanto costerebbero 5 secondi a 720p con ciascuno?”
• “Genera un video di 5 secondi a 720p con Seedance 2.0 Fast: una barchetta di carta che scivola lungo una strada al neon sotto la pioggia, con un lento avvicinamento della camera. Prima dimmi il prezzo.”
• “Crea quattro foto di prodotto di questa tazza con Seedream 5.0 Lite, ciascuna a meno di $0.05: https://example.com/mug.png”
• “Anima questa foto trasformandola in una clip verticale di 6 secondi con Wan 3.0: https://example.com/portrait.jpg”
• “Anima la foto sul mio desktop (~/Desktop/beach.jpg) in una clip di 5 secondi con Kling 3.0. Dimmi prima il prezzo.”
• “Da immagine a video con Seedance 2.0: @Image1 è il personaggio, @Image2 la strada; muovi la camera come in @Video1. Ecco gli URL: …”
• “Qual è il mio saldo CheaperGen e quante clip Seedance 2.0 da 10 secondi a 1080p posso permettermi?”

Agent Skill#

Lo skill CheaperGen è un singolo SKILL.md nel formato Agent Skills. Insegna all’agente l’intero flusso: scegliere un modello, leggere lo schema, calcolare un preventivo, inviare la richiesta, fare polling o verificare i webhook, citare riferimenti, caricare file e gestire prezzi ed errori. Gli agenti lo caricano solo quando serve. Per le chiamate REST legge la chiave da CHEAPERGEN_API_KEY e, quando sono connessi, preferisce gli strumenti MCP. Il sorgente è github.com/CheaperGen/skills.

/plugin marketplace add CheaperGen/skills
/plugin install cheapergen@cheapergen

npx skills add CheaperGen/skills

mkdir -p ~/.claude/skills/cheapergen
curl -fsSL https://cheapergen.com/skills/cheapergen/SKILL.md -o ~/.claude/skills/cheapergen/SKILL.md

mkdir -p .claude/skills/cheapergen
curl -fsSL https://cheapergen.com/skills/cheapergen/SKILL.md -o .claude/skills/cheapergen/SKILL.md

La CLI skills installa la skill in Claude Code, Cursor, Codex, Gemini CLI e altri agenti (-a consente di sceglierne uno, -g di installarla per tutti i progetti). Nelle app Claude, comprimi la cartella cheapergen e caricala come skill personalizzata.

Limiti e fatturazione#

• Gli stessi limiti di frequenza dell’API REST si applicano a ogni app o chiave connessa (ogni richiesta MCP viene conteggiata), così come il limite per account alle generazioni in corso.
• Il prezzo viene trattenuto dal saldo quando generate invia la richiesta e rimborsato integralmente se la generazione non riesce o viene annullata. Consulta Fatturazione e crediti.
• Le generazioni create tramite MCP compaiono nella dashboard e in GET /api/v1/generations con source: "mcp".
• I token di accesso durano un'ora e il client li rinnova automaticamente. Scollegare l'app dalla dashboard termina subito il suo accesso.
• Gli URL dei risultati sono pubblici e scadono secondo l'impostazione di conservazione dell'API (un giorno per impostazione predefinita). Scarica ciò che vuoi conservare.

Risoluzione dei problemi#

• Il client segnala che il server richiede l'autenticazione: completa l’accesso che ha avviato (in Claude Code: /mcp → cheapergen → Autentica). Se hai scollegato l’app o non l’hai usata per 90 giorni, accedi di nuovo.
• La pagina di accesso segnala che l'app non è registrata oppure che l'URL di reindirizzamento non corrisponde: rimuovi il server dal client e aggiungilo di nuovo, così il client può registrarsi ancora.
• Una chiamata a uno strumento va in timeout: riduci wait_seconds. La generazione continua comunque; recuperala più tardi con get_generation.
• invalid_request: l’input non corrisponde allo schema dell’endpoint. L’errore indica il campo in param; chiedi all’agente di chiamare prima get_model.