Come collegare Zuora a Gemini via MCP

💡 Niente installazione? Vai direttamente su cloud.anythingmcp.com. Accedi, clicca Connectors → Zuora, inserisci le credenziali, genera una MCP API key e hai finito. Niente Docker, niente git clone, niente server locale.

Zuora + Gemini

Zuora Billing REST API per un tenant: account cliente, abbonamenti e ordini con anteprima, rinnovo, sospensione e ripresa, fatture con righe e PDF, pagamenti, rimborsi e note di credito, il catalogo prodotti con i rate plan, i consumi e le letture ZOQL, Object Query e Data Query. OAuth2 client credentials, nessun accesso dal browser. Cancellazioni, pagamenti e rimborsi sono disattivati all'installazione.

Prerequisiti

Le istruzioni di setup complete sono incluse nel connettore stesso (visibili nello store quando lo selezioni). Le variabili d'ambiente richieste sono:

ZUORA_CLIENT_ID, ZUORA_CLIENT_SECRET, ZUORA_API_URL

Step 1 — Ottieni le credenziali

La configurazione richiede circa 5 minuti. Ti servono un tenant Zuora e l'accesso alla gestione utenti.

1. In Zuora apri Settings, Administration, Manage Users e scegli o crea un utente API il cui ruolo abbia i permessi necessari ai tool: accesso API e permessi di lettura per Billing e Payments, più i permessi di scrittura per i tool che modificano dati.
2. Apri quell'utente e crea un client in OAuth Clients. Copia il client id in ZUORA_CLIENT_ID e il client secret in ZUORA_CLIENT_SECRET. Il secret viene mostrato una sola volta; se lo perdi, crea un nuovo client.
3. Imposta ZUORA_API_URL sull'host REST del tuo tenant, senza percorso né barra finale: https://rest.zuora.com (US Cloud 2), https://rest.na.zuora.com (US Cloud 1), https://rest.eu.zuora.com (EU), https://rest.ap.zuora.com (APAC) oppure un host sandbox: https://rest.apisandbox.zuora.com, https://rest.sandbox.na.zuora.com, https://rest.sandbox.eu.zuora.com, https://rest.test.zuora.com, https://rest.test.eu.zuora.com o https://rest.test.ap.zuora.com. Zuora mostra l'host nelle informazioni del tenant e nell'indirizzo della documentazione API del tuo data center.
4. Installa il connettore ed esegui zuora_list_products: elenca il catalogo prodotti e conferma la configurazione.

Non c'è nessun accesso dal browser. AnythingMCP ottiene un access token da /oauth/token su quell'host con il grant OAuth2 client credentials e lo rinnova prima che scada. Un client sandbox funziona solo sul suo host sandbox. Su un tenant Multi-entity il client OAuth deve appartenere all'entity che vuoi leggere.

Cosa legge: account cliente con zuora_list_accounts (filtri Object Query come ["status.EQ:Active", "balance.GT:0"]), zuora_get_account, zuora_get_account_summary (contatti, abbonamenti, ultime fatture, pagamenti e consumi in una chiamata) e zuora_list_account_payment_methods (numeri mascherati); abbonamenti con zuora_list_subscriptions, zuora_list_account_subscriptions e zuora_get_subscription; ordini con zuora_list_orders e zuora_get_order; fatture con zuora_list_invoices (quelle scadute ad esempio con ["status.EQ:Posted", "balance.GT:0", "duedate.LT:2026-10-01"]), zuora_get_invoice, zuora_list_invoice_items e zuora_list_invoice_files (link di download dei PDF); pagamenti con zuora_list_payments e zuora_get_payment, rimborsi con zuora_list_refunds e zuora_get_refund, note di credito con zuora_list_credit_memos, zuora_get_credit_memo e zuora_list_credit_memo_items; il catalogo prodotti con zuora_list_products, zuora_get_product, zuora_list_product_rate_plans e zuora_get_product_rate_plan (gli id dei rate plan vanno negli ordini come productRatePlanId); i record di consumo con zuora_list_usages.

Query: zuora_query esegue ZOQL su un oggetto, ad esempio SELECT Id, Name, Balance FROM Account WHERE Status = 'Active', e zuora_query_more recupera il blocco successivo. Per SQL su più oggetti con join e totali, zuora_create_data_query avvia un job Data Query e l'AI chiama zuora_get_data_query finché queryStatus è completed; il risultato è un link di download temporaneo in dataFile. zuora_list_data_queries mostra i job precedenti e zuora_describe_object elenca i campi di un oggetto (in XML). Tutti i tool di query sono in sola lettura.

Cosa scrive: zuora_create_account e zuora_update_account. Le modifiche agli abbonamenti passano dagli ordini: zuora_preview_order mostra righe di fattura e importi senza salvare nulla, poi zuora_create_order crea un nuovo abbonamento, aggiunge o rimuove un prodotto o cambia quantità, prezzo o durata. zuora_renew_subscription rinnova un abbonamento a termine senza fatturare, zuora_suspend_subscription ferma la fatturazione finché zuora_resume_subscription non la fa ripartire. zuora_email_invoice invia per email una fattura registrata in PDF, zuora_create_credit_memo_from_invoice crea una nota di credito per tutte o alcune righe di una fattura (in Draft se auto_post non è true) e zuora_create_usage carica un record di consumo. Queste azioni cambiano ciò che viene fatturato ai clienti, quindi l'AI prepara l'anteprima, ti mostra gli importi e aspetta il tuo sì. zuora_create_order con processing_options (runBilling, collectPayment) emette anche la fattura e addebita il cliente.

Disattivati all'installazione: zuora_cancel_subscription, zuora_create_payment e zuora_refund_payment. Muovono denaro o non si possono annullare, quindi un admin del workspace li attiva quando servono al team.

Formati dei dati: la maggior parte delle chiavi (account_key, subscription_key, invoice_key) accetta il numero (A00000001, A-S00000001, INV00000001) o l'id di 32 caratteri; filtri come accountId richiedono l'id. Gli importi sono numeri decimali nella valuta dell'account. Le date sono YYYY-MM-DD; i timestamp sono nel fuso orario del tenant, a meno che non finiscano con Z. Le risposte v1 contengono success: true oppure success: false con reasons (codice e messaggio); le risposte Object Query contengono data.

Paginazione: le liste Object Query (zuora_list_accounts, zuora_list_subscriptions, zuora_list_invoices, zuora_list_usages) restituiscono fino a page_size record (10 di default, al massimo 99) e nextPage, che l'AI ripassa come cursor finché non manca. Le altre liste accettano page e page_size e restituiscono un link nextPage finché ci sono altri risultati. ZOQL restituisce fino a 2.000 record e done: false con un queryLocator per il resto.

Errori comuni: 400 al momento del token significa che Zuora non ha emesso il token: controlla client id e secret e che ZUORA_API_URL sia il data center del tuo tenant. 401 indica client id o secret errati oppure l'host sbagliato. 403 indica che all'utente API manca un permesso. 404 indica un numero o un id errato. Gli errori nelle risposte v1 possono arrivare anche con HTTP 200 e success: false; l'AI legge reasons. 429 significa che è stato raggiunto il limite di Zuora sulle richieste contemporanee per tenant o sulle richieste orarie per utente: aspetta e riprova.

Con i tool attivi all'installazione il connettore non cancella abbonamenti, non incassa pagamenti e non emette rimborsi. Legge il catalogo prodotti ma non crea né modifica prodotti, rate plan o prezzi, non aggiunge metodi di pagamento e non elimina nulla.

Step 2 — Installa l'adapter

curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d

Step 3 — Aggiungi il connettore in Gemini

L'URL del tuo server: in AnythingMCP apri MCP Servers → il server su cui si trova questo connettore e copia il suo URL (https://cloud.anythingmcp.com/mcp/…). Usalo ovunque questa guida mostra YOUR_SERVER_ID.

Gemini CLI legge i server MCP da ~/.gemini/settings.json (su Windows %USERPROFILE%\.gemini\settings.json). Aggiungi:

{
  "mcpServers": {
    "anythingmcp": {
      "httpUrl": "https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID",
      "headers": { "X-API-Key": "YOUR_MCP_API_KEY" }
    }
  }
}

1. Crea una chiave API MCP in AnythingMCP da MCP Servers → il tuo server → API keys e incollala al posto di YOUR_MCP_API_KEY.
2. Salva il file e riavvia gemini.
3. Esegui /mcp in Gemini CLI (oppure gemini mcp list dal terminale): anythingmcp dovrebbe risultare connesso.
4. Inizia a scrivere prompt: Gemini CLI ora può chiamare i tool di Zuora.

Tool disponibili

Esempi di prompt

• "Quali account hanno fatture registrate scadute prima del 1° ottobre e ancora aperte? Mostra account, numero fattura e importo residuo."
• "Dammi un riepilogo dell'account A00001234: abbonamenti attivi, ultime fatture e ultimi pagamenti."
• "Mostrami in anteprima quanto costa aggiungere 5 posti del piano Pro all'abbonamento A-S00000120 dal primo del mese prossimo, prima di creare l'ordine."
• "Con una Data Query somma il saldo aperto delle fatture per cliente ed elenca i 10 più alti."
• "Invia di nuovo la fattura INV00004567 in PDF a [email protected]."

FAQ

Dove cerca i server MCP Gemini CLI? In ~/.gemini/settings.json per il tuo utente, oppure in .gemini/settings.json dentro un progetto. gemini mcp list mostra ogni server e se si connette.

Prossimi passi

• Landing del connettore
• Collegare a Claude
• Collegare a ChatGPT
• Collegare a Cursor
• Collegare a Meta Muse
• Collegare a Microsoft Copilot