Skip to Content
Nuova versione 12 disponibile 🎉
LicensingIntegrazione AIServer MCP

Server MCP di Babel Licensing Data Center

Il server MCP di Babel Licensing è un server Model Context Protocol  (MCP) scritto in Python che espone come strumenti tutte le funzioni dell’API di Babel Licensing. Gli assistenti AI come Claude possono così interagire direttamente con il tuo sistema Babel Licensing per la gestione delle licenze, le operazioni sui clienti, la gestione dei prodotti e altro ancora.

Che cos’è MCP?

Il Model Context Protocol (MCP) è uno standard aperto che permette agli assistenti AI di connettersi in modo sicuro a sistemi e origini dati esterni. I server MCP fanno da ponte tra i modelli AI e i tuoi sistemi aziendali, e consentono di interagire in linguaggio naturale con API, database e strumenti.

Funzionalità

  • Copertura completa dell’API: espone come strumenti MCP tutti gli oltre 90 endpoint dell’API di Babel Licensing
  • Configurazione tipizzata: configurazione basata su Pydantic con convalida automatica
  • Supporto dell’autenticazione: supporta l’autenticazione sia con chiave API sia con token Bearer
  • Rotazione giornaliera dei log: registrazione automatica nella cartella logs/ con rotazione giornaliera dei file
  • Set completo di strumenti: include strumenti per:
    • Autenticazione e gestione degli utenti
    • Operazioni sulle licenze (attivazione, disattivazione, convalida, richiesta, rilascio)
    • Gestione di clienti e contatti
    • Gestione di prodotti e ordini
    • Modelli di licenza e token
    • Webhook e gestione degli eventi
    • Report e log
    • Notifiche email
    • Impostazioni e configurazione del sistema

Requisiti

  • Python 3.10 o versione successiva
  • Accesso all’API di Babel Licensing (URL di base e credenziali)
  • Un client compatibile con MCP (per esempio Claude Desktop)

Installazione

Avvio rapido

macOS / Linux

  1. Estrai l’archivio e spostati nella cartella:
unzip babel-licensing-mcp-*.zip
cd babel-licensing-mcp-*
  1. Esegui lo script di installazione:
chmod +x setup.sh
./setup.sh
  1. Configura il tuo ambiente:
# Edit .env file with your Babel Licensing API credentials
nano .env

Windows

  1. Estrai l’archivio ZIP e spostati nella cartella in PowerShell

  2. Abilita l’esecuzione degli script PowerShell (se necessario):

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
  1. Esegui lo script di installazione:
.\setup.ps1
  1. Configura il tuo ambiente:
# Edit .env file with your Babel Licensing API credentials
notepad .env

Installazione manuale

Crea un ambiente virtuale

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Installa le dipendenze

pip install -r requirements.txt

Configura le variabili d’ambiente

cp .env.example .env
# Edit .env with your actual credentials

Configurazione

Il server richiede le seguenti variabili d’ambiente (configurate in .env):

# Babel Licensing API Base URL
BABEL_API_BASE_URL=https://your-babel-licensing-server.com
 
# Authentication - Use ONE of the following:
# Option 1: API Key
BABEL_API_KEY=your-api-key-here
 
# Option 2: Bearer Token
# BABEL_BEARER_TOKEN=your-bearer-token-here
 
# Optional Configuration
# BABEL_VERIFY_SSL=true           # Set to false for self-signed certificates
# BABEL_TIMEOUT=30                # Request timeout in seconds
# BABEL_CONTENT_TYPE=application/json  # Content type: application/json or application/toon
# DEBUG=false                      # Enable debug logging

Configurazione del tipo di contenuto

Il server supporta due tipi di contenuto per le richieste all’API:

  • application/json (predefinito): formato JSON standard
  • application/toon: formato TOON per casi d’uso specifici

Per usare il formato TOON, imposta la variabile d’ambiente BABEL_CONTENT_TYPE:

BABEL_CONTENT_TYPE=application/toon

Il client imposta automaticamente le intestazioni Content-Type e Accept appropriate per tutte le richieste all’API.

Utilizzo

Eseguire il server MCP

Opzione 1: usare il comando installato

babel-licensing-mcp

Opzione 2: esecuzione diretta

python src/server.py

Configurare i client AI

Il server MCP di Babel Licensing può essere usato con qualsiasi client AI compatibile con MCP, compresi Claude Desktop e Claude Code.

Configurare Claude Desktop

Aggiungi quanto segue al file di configurazione di Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "babel-licensing": {
      "command": "/absolute/path/to/babel-licensing-mcp/venv/bin/python",
      "args": [
        "/absolute/path/to/babel-licensing-mcp/src/server.py"
      ],
      "env": {
        "BABEL_API_BASE_URL": "https://your-babel-server.com",
        "BABEL_API_KEY": "your-api-key-here"
      }
    }
  }
}

Esempio con percorsi reali (macOS):

{
  "mcpServers": {
    "babel-licensing": {
      "command": "/Users/username/Projects/babel-licensing-mcp/venv/bin/python",
      "args": [
        "/Users/username/Projects/babel-licensing-mcp/src/server.py"
      ],
      "env": {
        "BABEL_API_BASE_URL": "https://api.babel-licensing.com",
        "BABEL_API_KEY": "abc123def456"
      }
    }
  }
}

Esempio con percorsi reali (Windows):

{
  "mcpServers": {
    "babel-licensing": {
      "command": "C:\\Users\\username\\Projects\\babel-licensing-mcp\\venv\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\username\\Projects\\babel-licensing-mcp\\src\\server.py"
      ],
      "env": {
        "BABEL_API_BASE_URL": "https://api.babel-licensing.com",
        "BABEL_API_KEY": "abc123def456"
      }
    }
  }
}

Nota: sostituisci /absolute/path/to/ con il percorso effettivo della cartella del tuo progetto. Puoi trovarlo eseguendo pwd (macOS/Linux) o cd (Windows) nella cartella del progetto.

Alternativa: usare il file .env

Invece di specificare le variabili d’ambiente nella configurazione di Claude Desktop, puoi creare un file .env nella cartella principale del progetto:

# Copy the example file
cp .env.example .env
 
# Edit with your credentials
BABEL_API_BASE_URL=https://your-babel-server.com
BABEL_API_KEY=your-api-key-here

Poi usa una configurazione di Claude Desktop più semplice:

{
  "mcpServers": {
    "babel-licensing": {
      "command": "/absolute/path/to/babel-licensing-mcp/venv/bin/python",
      "args": [
        "/absolute/path/to/babel-licensing-mcp/src/server.py"
      ]
    }
  }
}

Dopo la configurazione:

  1. Chiudi completamente Claude Desktop e riavvialo
  2. Avvia una nuova conversazione
  3. Cerca l’icona degli strumenti 🔨, che indica che i server MCP sono connessi
  4. Chiedi a Claude: “A quali strumenti di Babel Licensing hai accesso?”

Configurare Claude Code

Claude Code è un’estensione di VS Code che porta l’assistenza dell’AI direttamente nel tuo ambiente di sviluppo. Per usare il server MCP di Babel Licensing con Claude Code:

Passo 1: installa Claude Code

Installa l’estensione Claude Code dal marketplace di VS Code:

  1. Apri VS Code
  2. Vai a Extensions (Cmd+Shift+X su macOS, Ctrl+Shift+X su Windows/Linux)
  3. Cerca “Claude Code”
  4. Fai clic su Install

Passo 2: aggiungi il server MCP alle impostazioni

Apri le impostazioni di VS Code e aggiungi la configurazione del server MCP:

Opzione A: impostazioni dell’area di lavoro (consigliata per l’uso in un progetto specifico)

Crea o modifica .vscode/settings.json nella tua area di lavoro:

{
  "claude.mcpServers": {
    "babel-licensing": {
      "command": "/absolute/path/to/babel-licensing-mcp/venv/bin/python",
      "args": [
        "/absolute/path/to/babel-licensing-mcp/src/server.py"
      ],
      "env": {
        "BABEL_API_BASE_URL": "https://licensing.example.com",
        "BABEL_API_KEY": "your-api-key-here"
      }
    }
  }
}

Opzione B: impostazioni utente (per l’accesso globale da tutte le aree di lavoro)

  1. Apri la Command Palette (Cmd+Shift+P su macOS, Ctrl+Shift+P su Windows/Linux)
  2. Digita “Preferences: Open User Settings (JSON)”
  3. Aggiungi la configurazione claude.mcpServers:
{
  "claude.mcpServers": {
    "babel-licensing": {
      "command": "/Users/username/Projects/babel-licensing-mcp/venv/bin/python",
      "args": [
        "/Users/username/Projects/babel-licensing-mcp/src/server.py"
      ],
      "env": {
        "BABEL_API_BASE_URL": "https://licensing.example.com",
        "BABEL_API_KEY": "your-api-key-here"
      }
    }
  }
}

Passo 3: usa le variabili d’ambiente

Nella configurazione puoi fare riferimento alle variabili d’ambiente:

{
  "claude.mcpServers": {
    "babel-licensing": {
      "command": "/path/to/babel-licensing-mcp/venv/bin/python",
      "args": ["/path/to/babel-licensing-mcp/src/server.py"],
      "env": {
        "BABEL_API_BASE_URL": "${env:BABEL_URL}",
        "BABEL_API_KEY": "${env:BABEL_KEY}"
      }
    }
  }
}

Poi imposta le variabili d’ambiente nella shell prima di avviare VS Code:

# macOS/Linux
export BABEL_URL="https://licensing.example.com"
export BABEL_KEY="your-api-key-here"
code .
 
# Windows PowerShell
$env:BABEL_URL = "https://licensing.example.com"
$env:BABEL_KEY = "your-api-key-here"
code .

Passo 4: usa il file .env (l’approccio più semplice)

Configura il file .env nella cartella del server MCP con le tue credenziali, poi usa una configurazione minima:

{
  "claude.mcpServers": {
    "babel-licensing": {
      "command": "/path/to/babel-licensing-mcp/venv/bin/python",
      "args": ["/path/to/babel-licensing-mcp/src/server.py"]
    }
  }
}

Il server carica automaticamente le impostazioni dal file .env.

Passo 5: esempi di percorsi per ogni piattaforma

macOS:

{
  "claude.mcpServers": {
    "babel-licensing": {
      "command": "/Users/username/Projects/babel-licensing-mcp/venv/bin/python",
      "args": [
        "/Users/username/Projects/babel-licensing-mcp/src/server.py"
      ]
    }
  }
}

Windows:

{
  "claude.mcpServers": {
    "babel-licensing": {
      "command": "C:\\Users\\username\\Projects\\babel-licensing-mcp\\venv\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\username\\Projects\\babel-licensing-mcp\\src\\server.py"
      ]
    }
  }
}

Linux:

{
  "claude.mcpServers": {
    "babel-licensing": {
      "command": "/home/username/projects/babel-licensing-mcp/venv/bin/python",
      "args": [
        "/home/username/projects/babel-licensing-mcp/src/server.py"
      ]
    }
  }
}

Passo 6: usa i percorsi relativi

Per le configurazioni specifiche di un’area di lavoro puoi usare le variabili di VS Code:

{
  "claude.mcpServers": {
    "babel-licensing": {
      "command": "${workspaceFolder}/../babel-licensing-mcp/venv/bin/python",
      "args": [
        "${workspaceFolder}/../babel-licensing-mcp/src/server.py"
      ],
      "cwd": "${workspaceFolder}/../babel-licensing-mcp"
    }
  }
}

È utile quando il server MCP si trova in una cartella allo stesso livello della tua area di lavoro.

Passo 7: verifica l’installazione

Dopo la configurazione, ricarica VS Code per attivare il server MCP:

  1. Apri la Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
  2. Digita “Developer: Reload Window”
  3. Premi Enter

Per verificare che il server funzioni:

  1. Apri il pannello di Claude in VS Code
  2. Avvia una nuova conversazione
  3. Chiedi: “Quali funzionalità di Babel Licensing hai a disposizione?”
  4. Claude dovrebbe elencare tutti gli 86 strumenti disponibili

Suggerimenti per l’uso di Claude Code:

  1. Richieste che tengono conto del contesto: Claude Code vede il file corrente e l’area di lavoro, quindi puoi chiedere:

    • “In base a questo codice, crea una licenza per questo cliente”
    • “Genera una chiamata di attivazione della licenza per il prodotto in questo file”

  2. Generazione di codice: chiedi a Claude di generare codice che usa l’API di Babel Licensing:

    • “Scrivi un metodo C# che attivi una licenza con questi parametri”
    • “Crea uno script Python che interroghi tutte le licenze attive”

  3. Assistenza inline: seleziona del codice e chiedi a Claude:

    • “Controlla se questa chiave di licenza è valida”
    • “Trova il cliente associato a questa chiave utente”

  4. Operazioni su più file: Claude può aiutarti a coordinare la gestione delle licenze tra più file:

    • “Aggiorna le chiavi di licenza in tutti i file di configurazione”
    • “Trova tutte le chiavi di licenza scritte direttamente nel codice di questo progetto”

Risoluzione dei problemi di Claude Code:

Se il server MCP non si connette:

  1. Controlla lo stato dell’estensione: assicurati che l’estensione Claude Code sia attiva
  2. Verifica il percorso di Python: controlla che il percorso dell’ambiente virtuale sia corretto
  3. Controlla i log: visualizza l’output di Claude Code nel pannello Output di VS Code
  4. Ricarica la finestra: usa “Developer: Reload Window” dopo le modifiche alla configurazione
  5. Controlla i permessi: assicurati che l’eseguibile di Python abbia i permessi di esecuzione

Configurazione di più ambienti:

Puoi configurare ambienti Babel Licensing diversi:

{
  "claude.mcpServers": {
    "babel-licensing-prod": {
      "command": "/path/to/venv/bin/python",
      "args": ["/path/to/src/server.py"],
      "env": {
        "BABEL_API_BASE_URL": "https://licensing.production.com",
        "BABEL_API_KEY": "${env:BABEL_PROD_KEY}"
      }
    },
    "babel-licensing-dev": {
      "command": "/path/to/venv/bin/python",
      "args": ["/path/to/src/server.py"],
      "env": {
        "BABEL_API_BASE_URL": "https://licensing.dev.com",
        "BABEL_API_KEY": "${env:BABEL_DEV_KEY}"
      }
    }
  }
}

In questo modo puoi passare dall’ambiente di produzione a quello di sviluppo mentre lavori con Claude.

Log

Il server registra automaticamente tutte le operazioni in file di log giornalieri nella cartella logs/:

  • Posizione: logs/babel_licensing_YYYYMMDD.log
  • Formato: voci con data e ora, livello e informazioni sul modulo
  • Rotazione: crea automaticamente un nuovo file ogni giorno
  • Output: i log vengono scritti sia su file sia sulla console

Esempio di file di log: logs/babel_licensing_20251111.log

2025-11-11 10:30:15 - server - INFO - MCP server starting...
2025-11-11 10:30:16 - server - INFO - Babel Licensing client initialized
2025-11-11 10:31:22 - server - INFO - Tool called: babel_get_customers

Strumenti disponibili

Il server espone 86 strumenti organizzati nelle seguenti categorie:

Nota: l’autenticazione è gestita automaticamente tramite la chiave API o il token Bearer configurati nelle variabili d’ambiente. Gli strumenti di accesso interattivo non sono necessari.

Operazioni sulle licenze (7 strumenti)

  • babel_activate_license: attiva una licenza
  • babel_deactivate_license: disattiva una licenza
  • babel_request_license: richiede una licenza
  • babel_release_license: rilascia una licenza
  • babel_license_heartbeat: invia l’heartbeat della licenza
  • babel_validate_license: convalida una licenza
  • babel_get_license_info: ottiene le informazioni sulla licenza

Gestione

Chiavi API (4 strumenti)

  • babel_get_api_keys: elenca le chiavi API
  • babel_insert_api_key: crea una nuova chiave API
  • babel_update_api_key: aggiorna una chiave API
  • babel_delete_api_key: elimina una chiave API

Utenti (7 strumenti)

  • babel_get_users: elenca gli utenti
  • babel_insert_user: crea un utente
  • babel_update_user: aggiorna un utente
  • babel_delete_user: elimina un utente
  • babel_get_user_roles: ottiene i ruoli di un utente
  • babel_add_user_to_roles: aggiunge un utente ai ruoli
  • babel_remove_user_from_roles: rimuove un utente dai ruoli

Clienti (7 strumenti)

  • babel_get_customers: elenca i clienti
  • babel_insert_customer: crea un cliente
  • babel_update_customer: aggiorna un cliente
  • babel_delete_customer: elimina un cliente
  • babel_get_customer_contacts: ottiene i contatti di un cliente
  • babel_get_customer_orders: ottiene gli ordini di un cliente
  • babel_get_customer_licenses: ottiene le licenze di un cliente

Prodotti (15 strumenti)

  • Gestione dei prodotti (lettura, inserimento, aggiornamento, eliminazione)
  • Gestione dei rilasci dei prodotti
  • Gestione degli assembly dei rilasci
  • Modelli di licenza dei rilasci

Ordini (9 strumenti)

  • Gestione degli ordini (lettura, inserimento, aggiornamento, eliminazione)
  • Gestione dei prodotti degli ordini
  • Recupero delle licenze degli ordini

Licenze (9 strumenti)

  • Gestione delle licenze (lettura, inserimento, aggiornamento, eliminazione)
  • Gestione dei token di licenza
  • Tracce delle licenze
  • Modelli di licenza

Webhook (9 strumenti)

  • Gestione delle sottoscrizioni webhook
  • Recupero dei tipi di evento
  • Test dei webhook
  • Gestione degli eventi

Altri strumenti di gestione

  • Assembly (4 strumenti)
  • Contatti (4 strumenti)
  • Risorse (4 strumenti)
  • Report (3 strumenti)
  • Log (3 strumenti)
  • Impostazioni (2 strumenti)
  • Email (2 strumenti)
  • Informazioni sul server (1 strumento)

Lavorare con l’API

Formato dei dati per le operazioni di inserimento e aggiornamento

Quando usi gli strumenti che creano o aggiornano risorse (quelli il cui nome inizia con babel_insert_ o babel_update_), il client racchiude automaticamente i tuoi dati nel formato di richiesta previsto dall’API di Babel Licensing.

Devi fornire solo i dati grezzi: l’incapsulamento è gestito automaticamente.

Esempi

Creare un nuovo cliente:

// You provide:
{
  "customer_data": {
    "name": "Acme Corporation",
    "email": "contact@acme.com"
  }
}
 
// The client automatically wraps it as:
{
  "customer": {
    "name": "Acme Corporation",
    "email": "contact@acme.com"
  }
}

Creare un nuovo utente:

// You provide:
{
  "user_data": {
    "userName": "johndoe",
    "email": "john@example.com",
    "password": "SecureP@ssw0rd"
  }
}
 
// The client automatically wraps it as:
{
  "user": {
    "userName": "johndoe",
    "email": "john@example.com"
  },
  "password": "SecureP@ssw0rd"
}

Aggiornare una licenza:

// You provide:
{
  "license_data": {
    "id": 123,
    "revoked": false,
    "description": "Updated description"
  }
}
 
// The client automatically wraps it as:
{
  "license": {
    "id": 123,
    "revoked": false,
    "description": "Updated description"
  }
}

Parametri di query

Molti endpoint GET supportano i seguenti parametri di query:

  • select: elenco separato da virgole dei nomi dei campi da includere nella risposta
  • filter: criteri di filtro con la sintassi .NET (vedi Sintassi dei filtri più avanti)
  • include: elenco separato da virgole degli oggetti correlati da includere (vedi Parametro include più avanti)
  • sort: nome del campo, con ‘asc’ o ‘desc’ facoltativi
  • take: limite di paginazione (dimensione della pagina)
  • skip: offset di paginazione

Parametro include

Il parametro include ti permette di recuperare gli oggetti correlati in un’unica richiesta.

Regole IMPORTANTI:

  1. Usa i nomi in PascalCase (con l’iniziale maiuscola): Customer, Order, Product (NON customer, order, product)
  2. DEVI aggiungere a select gli oggetti inclusi: indicali in entrambi i parametri
  3. Più oggetti: separali con una virgola, senza spazi

Esempi:

// Correct - Get licenses with customer and order objects
{
  "params": {
    "select": "id,licenseId,licenseType,createdAt,customerId,orderId,Customer,Order",  //  Include Customer,Order here
    "include": "Customer,Order"  //  PascalCase, no spaces
  }
}
 
// Wrong - lowercase names
{
  "params": {
    "select": "id,licenseId,customer,order",  // L Lowercase
    "include": "customer,order"  // L Will fail
  }
}
 
// Wrong - missing from select
{
  "params": {
    "select": "id,licenseId,licenseType",  // L Missing Customer,Order
    "include": "Customer,Order"  // Objects won't be returned!
  }
}

Opzioni di include disponibili:

  • babel_get_licenses: Product, Order, Customer, Template, Licensee
  • babel_get_customers: Contacts, Orders, Licenses
  • babel_get_orders: Customer, Reseller, Products, Licenses
  • babel_get_products: Releases, Orders
  • babel_get_users: Roles, Settings, Customer
  • babel_get_api_keys: Owner
  • babel_get_all_license_tokens: License, NodeLockedLicense
  • babel_get_license_templates: Product

Sintassi dei filtri

L’API usa la sintassi dei filtri .NET, NON lo standard OData.

Operatori di confronto:

OperatoreDescrizioneEsempio
>=Maggiore o ugualecreatedAt >= "2025-11-11T00:00:00"
<=Minore o ugualeexpireDate <= "2025-12-31T23:59:59"
>Maggioreid > 100
<Minoreid < 1000
==Ugualerevoked == false
!=Diversostatus != "expired"

Operatori logici:

OperatoreDescrizioneEsempio
&&AND logicorevoked == false && expireDate >= "2025-01-01"
||OR logicostatus == "active" || status == "trial"
!Negazione (NOT)!revoked o !licenseType.Contains("Trial")

Funzioni per le stringhe:

FunzioneDescrizioneEsempio
Contains()Verifica se la stringa contiene una sottostringalicenseType.Contains("Ultimate")
StartsWith()Verifica se la stringa inizia con una sottostringauserKey.StartsWith("ABC")
EndsWith()Verifica se la stringa termina con una sottostringalicenseeEmail.EndsWith("@example.com")

Esempi di filtri complessi:

# Active licenses of Ultimate type created after Nov 11
revoked == false && licenseType.Contains("Ultimate") && createdAt >= "2025-11-11T00:00:00"

# Exclude Enterprise licenses
!licenseType.Contains("Enterprise")

# User keys starting with ABC or XYZ
userKey.StartsWith("ABC") || userKey.StartsWith("XYZ")

# Expired licenses excluding trial
expireDate < "2025-01-01T00:00:00" && !licenseType.Contains("Trial")

IMPORTANTE: NON usare la sintassi OData (eq, ne, gt, lt, and, or). Questi operatori non funzionano.

Parametro sort:

Il parametro sort accetta:

  • Nome del campo con direzione: createdAt desc (decrescente)
  • Nome del campo con direzione: createdAt asc (crescente)
  • Solo il nome del campo: createdAt (crescente per impostazione predefinita)

Esempio completo:

{
  "params": {
    "filter": "revoked == false && licenseType.Contains(\"Ultimate\") && expireDate >= \"2025-01-01T00:00:00\"",
    "select": "id,licenseId,userKey,expireDate,licenseType",
    "take": 10,
    "skip": 0,
    "sort": "createdAt desc"
  }
}

Esempi

Attivare una licenza

Chiedi a Claude:

“Attiva una licenza con chiave utente ABC-123-DEF, codice prodotto PROD001 e ID hardware HW-12345”

Claude userà lo strumento babel_activate_license:

{
  "tool": "babel_activate_license",
  "arguments": {
    "license_data": {
      "userKey": "ABC-123-DEF",
      "productCode": "PROD001",
      "hardwareId": "HW-12345"
    }
  }
}

Ottenere i clienti

Chiedi a Claude:

“Mostrami i primi 10 clienti rivenditori, ordinati per nome dell’azienda”

Claude userà lo strumento babel_get_customers:

{
  "tool": "babel_get_customers",
  "arguments": {
    "params": {
      "filter": "isReseller == true",
      "take": 10,
      "sort": "company asc"
    }
  }
}

Creare una sottoscrizione webhook

Chiedi a Claude:

“Crea una sottoscrizione webhook per gli eventi di attivazione e disattivazione delle licenze che punti a https://example.com/webhook ”

Claude userà lo strumento babel_create_webhook_subscription:

{
  "tool": "babel_create_webhook_subscription",
  "arguments": {
    "subscription_data": {
      "url": "https://example.com/webhook",
      "events": ["license.activated", "license.deactivated"],
      "isActive": true
    }
  }
}

Esempio di query complessa

Chiedi a Claude:

“Mostrami tutte le licenze Ultimate create dopo l’11 novembre 2025 e non revocate, con i dettagli del cliente e dell’ordine, ordinate per data di creazione”

Claude costruirà una query come questa:

{
  "tool": "babel_get_licenses",
  "arguments": {
    "params": {
      "filter": "revoked == false && licenseType.Contains(\"Ultimate\") && createdAt >= \"2025-11-11T00:00:00\"",
      "select": "id,licenseId,userKey,expireDate,licenseType,createdAt,Customer,Order",
      "include": "Customer,Order",
      "sort": "createdAt desc"
    }
  }
}

Risoluzione dei problemi

Problemi di connessione

  1. Verifica che il valore di BABEL_API_BASE_URL sia corretto
  2. Assicurati che la chiave API o il token Bearer siano validi
  3. Controlla la connettività di rete verso il server di Babel Licensing
  4. Consulta i log del server nella cartella logs/ per i messaggi di errore dettagliati

Problemi con i certificati SSL

Se riscontri errori di verifica del certificato SSL (soprattutto con i certificati autofirmati):

  1. Imposta BABEL_VERIFY_SSL=false nel file .env o nella configurazione dell’ambiente
  2. Per Claude Desktop, aggiungila alla sezione env: 
    {
  "mcpServers": {
    "babel-licensing": {
      "command": "/path/to/venv/bin/python",
      "args": ["/path/to/src/server.py"],
      "env": {
        "BABEL_API_BASE_URL": "https://your-server.com",
        "BABEL_API_KEY": "your-key",
        "BABEL_VERIFY_SSL": "false"
      }
    }
  }
}

Nota di sicurezza: disabilita la verifica SSL solo per i server interni attendibili con certificati autofirmati. Non disabilitarla mai per i sistemi di produzione o per le API pubbliche.

Errori di autenticazione

  1. Assicurati di usare UN SOLO metodo di autenticazione (chiave API OPPURE token Bearer)
  2. Verifica che le tue credenziali non siano scadute
  3. Controlla che la chiave API abbia i permessi necessari

Errori di esecuzione degli strumenti

  1. Controlla lo schema di input dello strumento che stai usando
  2. Assicurati di fornire tutti i parametri obbligatori
  3. Verifica che i tipi dei parametri corrispondano allo schema
  4. Esamina la risposta dell’API per i messaggi di errore specifici

Saturazione dei token con babel_get_logs

Lo strumento babel_get_logs può restituire quantità di dati molto grandi, soprattutto quando includi i campi exception e properties. Questo può saturare i token AI disponibili nella conversazione.

Indicazioni per la scelta dei campi:

  • exception e properties: possono contenere quantità di dati molto grandi; evitali quando richiedi molti record
  • messageTemplate: non è strettamente necessario, perché contiene solo il modello di formattazione; il contenuto informativo vero e proprio è in message
  • Campi consigliati: id, message, level, timeStamp

Procedure consigliate:

  1. Limita i campi in select: evita di includere exception, properties e messageTemplate se non ti servono davvero

    # Good - excludes large/unnecessary fields
{
  "params": {
    "select": "id,message,level,timeStamp",
    "take": 50
  }
}
 
# Risky - includes large fields
{
  "params": {
    "select": "id,message,level,timeStamp,exception,properties",
    "take": 50  # May saturate tokens
  }
}

  2. Usa la paginazione con criterio: quando includi exception o properties, usa valori di take piccoli (10-20 record al massimo)

  3. Filtra prima di recuperare: usa il parametro filter per ridurre il numero di record prima di recuperarli

Documentazione dell’API

Per informazioni dettagliate sugli endpoint, i parametri e le risposte dell’API di Babel Licensing, consulta il file di specifica OpenAPI babel-licensing-api.json incluso nel pacchetto del server MCP.

Assistenza

Per problemi o domande, scrivi a: support@babelfor.net

Risorse

Cronologia delle versioni

  • 0.1.0 (versione iniziale)
    • Implementazione completa di tutti gli endpoint dell’API di Babel Licensing
    • Supporto dell’autenticazione, delle operazioni sulle licenze e delle funzioni di gestione
    • Suite di test completa
    • Documentazione completa
Last updated on