Chiavi API - Syrto

La maggior parte dei client MCP si collega a Syrto facendoti accedere con OAuth: aggiungi l’URL del server e segui la richiesta di login, come descritto in Configurazione. Serve quindi una persona davanti allo schermo. Per script, job pianificati, pipeline di CI e integrazioni server-to-server, il server MCP di Syrto accetta anche una chiave API di organizzazione inviata come bearer token. Non c’è alcun flusso di accesso: la chiave viene verificata a ogni richiesta.

Accesso o chiave API

	Accesso (OAuth)	Chiave API di organizzazione
Identifica	Te e la tua organizzazione	Solo la tua organizzazione, nessuna persona
Adatto a	Assistenti AI usati da persone	Script, automazioni, integrazioni server-to-server
Strumenti disponibili	Tutti	Tutti tranne i cinque che richiedono una persona
Limiti di frequenza	Conteggiati per persona	Condivisi da tutte le chiavi dell’organizzazione
Consumi addebitati a	La tua organizzazione	La tua organizzazione

Crea una chiave

Le chiavi API vengono create da un amministratore dell’organizzazione nella dashboard Syrto, in Impostazioni → Chiavi API. Sono le stesse chiavi di organizzazione usate dalla API Syrto, quindi una chiave che hai già per la API funziona anche qui. Le chiavi iniziano con sk_. Trattale come una password: danno accesso ai dati della tua organizzazione e ne consumano il plafond. Conservale in un archivio di segreti o in una variabile d’ambiente, mai in un URL, in un prompt o in un file che finisce nel repository.

Sono accettate solo le chiavi di organizzazione. Le chiavi personali che puoi creare in Profilo → Chiavi API vengono rifiutate con 401 Unauthorized, perché una chiave API è pensata per identificare un’organizzazione e non una persona. Per usare Syrto a tuo nome, accedi con OAuth.

Invia la chiave

Punta il client al server MCP di Syrto e invia la chiave nell’header Authorization:

URL:    https://mcp.syrto.ai/mcp
Header: Authorization: Bearer sk_...

Gli esempi qui sotto leggono la chiave dalla variabile d’ambiente SYRTO_API_KEY:

export SYRTO_API_KEY=sk_...

Claude Code
VS Code
HTTP

Aggiungi il server con un header Authorization fisso:

claude mcp add --transport http syrto https://mcp.syrto.ai/mcp \
  --header "Authorization: Bearer $SYRTO_API_KEY"

La shell espande $SYRTO_API_KEY quando esegui il comando, quindi Claude Code salva la chiave stessa nella sua configurazione.

Aggiungi il server a .vscode/mcp.json. La voce inputs fa sì che VS Code chieda la chiave una sola volta e la conservi in modo sicuro, così non compare mai nel file:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "syrto-api-key",
      "description": "Chiave API Syrto",
      "password": true
    }
  ],
  "servers": {
    "syrto": {
      "type": "http",
      "url": "https://mcp.syrto.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${input:syrto-api-key}"
      }
    }
  }
}

Qualsiasi client o SDK MCP in grado di inviare header HTTP personalizzati funziona allo stesso modo. Per verificare una chiave da riga di comando, invia una richiesta initialize:

curl -s https://mcp.syrto.ai/mcp \
  -H "Authorization: Bearer $SYRTO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

Una chiave valida restituisce il nome e le capacità del server. Un 401 Unauthorized significa che la chiave non è stata accettata: vedi Errori.

Cosa non può fare una chiave API

Una chiave di organizzazione non identifica alcuna persona, quindi gli strumenti per documenti ufficiali, contatti persona e consumi personali non vengono proposti su una connessione con chiave:

Strumento	Perché richiede una persona
`syrto_list_official_documents`	Riporta il saldo crediti dell’organizzazione, disponibile solo a un utente connesso
`syrto_request_official_document`	Spende i crediti dell’organizzazione per conto di qualcuno
`syrto_get_person_contacts`	Registra chi ha cercato la persona e riporta il saldo crediti
`syrto_request_person_contacts`	Spende i crediti dell’organizzazione per conto di qualcuno
`syrto_get_usage`	Riporta i consumi di una singola persona

Non compaiono nell’elenco degli strumenti, e chiamarne uno comunque restituisce un errore che indica che lo strumento richiede un utente connesso. Tutti gli altri strumenti funzionano con una chiave, compresi la ricerca di aziende e persone, i profili aziendali, la struttura, le metriche e le analisi.

Limiti di frequenza e consumi

Quando usi una chiave API, i limiti di frequenza si applicano all’organizzazione nel suo insieme: tutte le chiavi dell’organizzazione attingono a un unico insieme di limiti condiviso, quindi creare altre chiavi non li aumenta. Tienine conto prima di collegare una pipeline ad alto volume a una chiave. I consumi fatti con una chiave vengono addebitati al plafond Syrto AI dell’organizzazione, come quelli dei membri che accedono con il proprio account.

Revoca una chiave

Un amministratore elimina le chiavi dalla stessa pagina Impostazioni → Chiavi API della dashboard. Una chiave eliminata o scaduta smette di funzionare entro circa un minuto.

Errori

Una chiave non accettata riceve sempre 401 Unauthorized. Le cause più comuni:

Manca l’header Authorization, oppure non è nella forma Bearer sk_....
La chiave è scritta male, eliminata o scaduta.
La chiave è una chiave personale di Profilo → Chiavi API invece di una chiave di organizzazione.

​Accesso o chiave API

​Crea una chiave

​Invia la chiave

​Cosa non può fare una chiave API

​Limiti di frequenza e consumi

​Revoca una chiave

​Errori

Accesso o chiave API

Crea una chiave

Invia la chiave

Cosa non può fare una chiave API

Limiti di frequenza e consumi

Revoca una chiave

Errori