BananaBanana MCP Server

Un server Model Context Protocol remoto che espone l'intero stack di generazione di BananaBanana come tool per agenti: immagini Google Nano Banana 2 Lite / 2 / Pro (da $0.03), video Veo 3.1 / Fast / Lite e Gemini Omni Flash, Wan 3.0 con audio ($0.09–1.00). Il tuo agente vede i prezzi aggiornati, conferma i costi prima delle generazioni costose e ogni risultato finisce nella stessa cronologia e sullo stesso saldo del sito.

• Endpoint: https://bananabanana.pro/api/mcp (Streamable HTTP)
• Autenticazione: accesso con OAuth 2.1 (claude.ai e altri client a connettore) oppure chiave API Bearer dal tuo profilo
• Limite di frequenza: 20 chiamate ai tool al minuto per chiave; tetto di spesa giornaliero per chiave facoltativo
• Niente client MCP? Lo stesso endpoint è semplice JSON-RPC su HTTPS: chiamalo da curl, Python o TypeScript senza alcun SDK
• Le generazioni fallite o bloccate dal filtro vengono rimborsate automaticamente
• Documentazione aperta, server.json ed esempi per i client da copiare e incollare nel repository GitHub bananabanana-mcp

1. Crea un account e ricarica il saldo. 2. In Profilo → Chiavi API MCP crea una chiave (viene mostrata una sola volta). 3. Aggiungi il server al tuo client:

claude.ai, Claude Desktop, mobile (OAuth, niente da copiare)

Settings → Connectors → Add custom connector, incolla https://bananabanana.pro/api/mcp e premi Connect. Claude si registra da solo, tu approvi l'accesso in una schermata di BananaBanana e le generazioni vengono addebitate all'account con cui hai effettuato l'accesso.

Settings → Connectors → Add custom connector
URL: https://bananabanana.pro/api/mcp
→ Add → Connect → approve access on bananabanana.pro

Lo stesso flusso funziona in qualsiasi client che implementa l'autorizzazione MCP: MCP Inspector, i connettori web di ChatGPT e Grok, Claude Code. Le app collegate sono elencate nel tuo profilo e puoi scollegarle da lì in qualsiasi momento.

Claude Code

# with an API key
claude mcp add --transport http bananabanana https://bananabanana.pro/api/mcp \
  --header "Authorization: Bearer bb_live_YOUR_KEY"

# or with OAuth — no key, sign in in the browser
claude mcp add --transport http bananabanana https://bananabanana.pro/api/mcp
# then run /mcp inside Claude Code and pick "Authenticate"

Claude Desktop

Aggiungi a claude_desktop_config.json (Settings → Developer → Edit Config); serve Node.js per il bridge mcp-remote:

{
  "mcpServers": {
    "bananabanana": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://bananabanana.pro/api/mcp",
        "--header", "Authorization: Bearer bb_live_YOUR_KEY"
      ]
    }
  }
}

Cursor

Aggiungi a ~/.cursor/mcp.json (globale) oppure a .cursor/mcp.json nel progetto; per non lasciare la chiave nel file, usa ${env:BB_API_KEY} al posto del valore letterale:

{
  "mcpServers": {
    "bananabanana": {
      "url": "https://bananabanana.pro/api/mcp",
      "headers": {
        "Authorization": "Bearer bb_live_YOUR_KEY"
      }
    }
  }
}

Guida completa per Cursor, con le sue stranezze e una demo con chiave reale: Generare immagini in Cursor.

VS Code / GitHub Copilot

Aggiungi a .vscode/mcp.json nel workspace (o nel tuo settings.json utente); VS Code chiede la chiave una volta e la conserva cifrata:

{
  "servers": {
    "bananabanana": {
      "type": "http",
      "url": "https://bananabanana.pro/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:bb-api-key}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "bb-api-key",
      "description": "BananaBanana API key (bb_live_…)",
      "password": true
    }
  ]
}

Guida completa per VS Code / Copilot, con le sue stranezze e una demo con chiave reale: Generare immagini in VS Code: guida alla configurazione MCP di Copilot.

Windsurf

Aggiungi a ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "bananabanana": {
      "serverUrl": "https://bananabanana.pro/api/mcp",
      "headers": {
        "Authorization": "Bearer bb_live_YOUR_KEY"
      }
    }
  }
}

Windsurf MCP Setup: Generate Images in Cascade

Cline

{
  "mcpServers": {
    "bananabanana": {
      "type": "streamableHttp",
      "url": "https://bananabanana.pro/api/mcp",
      "headers": {
        "Authorization": "Bearer bb_live_YOUR_KEY"
      },
      "disabled": false,
      "autoApprove": ["list_models", "get_account", "get_result"]
    }
  }
}

Cline MCP Server: Generate Images From Your Editor

Qualsiasi altro client MCP (JSON-RPC diretto)

POST https://bananabanana.pro/api/mcp
Authorization: Bearer bb_live_YOUR_KEY
Content-Type: application/json
Accept: application/json, text/event-stream

{"jsonrpc":"2.0","id":1,"method":"tools/list"}

Ogni metodo tranne ping e le liste di discovery (tools/list, prompts/list, resources/list) richiede una credenziale, initialize compreso: un handshake non autenticato risponde 401 con una challenge WWW-Authenticate. L'asimmetria è voluta, non è un bug: è proprio con quella challenge che un client a connettore scopre che questo server usa OAuth. Leggere il catalogo dei tool senza chiave funziona comunque.

Preferisci una guida passo passo? Il tutorial Generare immagini in Claude Code copre la configurazione di Claude dall'inizio alla fine, con quattro casi d'uso reali e i loro costi effettivi.

MCP è un protocollo aperto: si collega qualsiasi client che parli Streamable HTTP e sappia allegare un header Authorization. Situazione attuale, verificata sulla documentazione ufficiale di ciascun produttore (ultimo controllo: agosto 2026):

Esempio per Codex: aggiungi a ~/.codex/config.toml ed esporta BB_API_KEY=bb_live_…:

[mcp_servers.bananabanana]
url = "https://bananabanana.pro/api/mcp"
bearer_token_env_var = "BB_API_KEY"

Guida completa per Codex (CLI, estensione IDE e ChatGPT desktop da un'unica configurazione), con le sue stranezze e una demo con chiave reale: Configurare Codex MCP: immagini e video da un solo config.toml.

Non usi un client MCP? Non ti serve, e non ti serve nemmeno un SDK. Il server è semplice JSON-RPC 2.0 su HTTPS: un endpoint POST, un header Bearer, una sola risposta JSON. È stateless, quindi non c'è nessun handshake di sessione da gestire: tools/call funziona già come prima richiesta da curl, Python, TypeScript o qualsiasi altra cosa sappia inviare HTTP.

curl

# start an image generation (charges one image, $0.03 on the default Lite model)
curl -s https://bananabanana.pro/api/mcp \
  -H "Authorization: Bearer bb_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{
        "name":"generate_image",
        "arguments":{"prompt":"studio photo of a ceramic mug on linen, soft daylight"}}}'

# → result.structuredContent.job_id = "cmxy…"

# fetch the result (long-polls server-side up to 30 s; free)
curl -s https://bananabanana.pro/api/mcp \
  -H "Authorization: Bearer bb_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{
        "name":"get_result",
        "arguments":{"job_id":"cmxy…","wait_seconds":30}}}'

Python

Solo requests, nessuna libreria MCP:

import requests

MCP = "https://bananabanana.pro/api/mcp"
HEADERS = {"Authorization": "Bearer bb_live_YOUR_KEY"}

def call(tool, **args):
    r = requests.post(MCP, headers=HEADERS, json={
        "jsonrpc": "2.0", "id": 1, "method": "tools/call",
        "params": {"name": tool, "arguments": args},
    })
    r.raise_for_status()
    return r.json()["result"]["structuredContent"]

job = call("generate_image", prompt="watercolor painting of a lighthouse at dawn")

result = call("get_result", job_id=job["job_id"], wait_seconds=30)
while result["status"] == "processing":
    result = call("get_result", job_id=job["job_id"], wait_seconds=30)

print(result["files"][0]["url"], "cost:", result["cost_charged_usd"])

TypeScript / Node.js

Zero dipendenze, il fetch integrato (Node 18+, Deno, Bun, browser):

const MCP = "https://bananabanana.pro/api/mcp";

async function call(tool: string, args: Record<string, unknown>) {
  const res = await fetch(MCP, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.BB_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      jsonrpc: "2.0", id: 1, method: "tools/call",
      params: { name: tool, arguments: args },
    }),
  });
  const { result } = await res.json();
  return result.structuredContent;
}

const job = await call("generate_image", {
  prompt: "isometric 3D render of a tiny greenhouse at golden hour",
});

let out = await call("get_result", { job_id: job.job_id, wait_seconds: 30 });
while (out.status === "processing") {
  out = await call("get_result", { job_id: job.job_id, wait_seconds: 30 });
}
console.log(out.files[0].url, "cost:", out.cost_charged_usd);

Dettagli che contano quando lo usi da script:

• Ogni risposta di un tool contiene lo stesso JSON due volte: result.structuredContent leggibile dalle macchine e un blocco di testo in result.content; usa quello che ti è più comodo.
• Video (e lotti di più immagini) richiedono due chiamate: la prima generate_video restituisce un preventivo e non addebita nulla; ripetila con confirm_cost impostato sull'importo del preventivo per avviare la generazione.
• Passa un idempotency_key nelle chiamate di generazione: i tentativi ripetuti per errori di rete non addebiteranno mai due volte.
• tools/list funziona senza chiave, così puoi esplorare tutti gli schemi prima di creare un account. Le chiamate ai tool sono limitate a 20 al minuto per chiave.

• I prezzi arrivano in tempo reale da list_models, la stessa fonte usata dal sito.
• Ogni chiamata video (e ogni lotto di più immagini) restituisce prima un preventivo senza addebitare nulla; l'agente ripete la chiamata con confirm_cost per avviarla.
• Ogni risultato include cost_charged_usd e balance_remaining_usd.
• Gli errori del provider e i rifiuti del filtro dei contenuti vengono rimborsati automaticamente, con la stessa regola dell'app web.
• Il parametro facoltativo idempotency_key garantisce che i tentativi ripetuti non addebitino mai due volte.

• Gli URL dei risultati sono firmati e validi 24 ore; i file restano nel tuo account: richiama get_result per avere link nuovi oppure scaricali dal sito.
• Le chiavi API sono salvate come hash e mostrate una sola volta alla creazione; puoi revocarle in qualsiasi momento dal profilo.
• Le connessioni OAuth usano access token da un'ora con refresh token a rotazione, salvati come hash e validi solo per questo server; scollegando un'app dal profilo i suoi token vengono invalidati all'istante.
• Il registro d'uso per chiave (tool, modello, costo, anteprima del prompt) è visibile in Profilo → Chiavi API MCP.
• Le generazioni via MCP compaiono nella stessa cronologia e nelle stesse statistiche delle generazioni fatte sul web.

x402 è un protocollo aperto che permette a un agente di pagare una singola richiesta con una stablecoin. È un endpoint separato dal server MCP: POST /api/x402. Non servono account, chiave API né ricarica.

1. Invia il nome del tool e i suoi argomenti. Il server risponde 402 con il prezzo esatto di quella chiamata.
2. Firma il pagamento in USDC sulla rete Base e ripeti la richiesta con l'header X-PAYMENT.
3. Immagini e parlato tornano nella stessa risposta. Il video restituisce un job_id; controlla lo stato con GET /api/x402/result/{jobId} gratis.

Tool disponibili: generate_image, generate_speech, generate_video. I prezzi sono gli stessi dello Studio web e di MCP; una chiamata costa quanto la generazione, senza ricarica minima.

Se un video pagato fallisce, chi ha pagato riceve un token di credito dello stesso importo, valido 90 giorni. Passalo come refund_token in una chiamata successiva. I pagamenti non vengono rimborsati on-chain. Il catalogo leggibile dalle macchine con i prezzi attuali è su GET /api/x402.