Skip to Content

Endpoint MCP

IronFlock è un server MCP. Claude, e ogni altro client che parla il Model Context Protocol, può elencare i tuoi progetti, leggerne dispositivi, app e dati, e agire su di essi con gli strumenti che IronFlock offre, entro ciò che la tua chiave API consente. L’endpoint fa parte dello stesso servizio API dell’API REST e usa le stesse chiavi API.

Indirizzo e Autenticazione

URL nel cloud IronFlockhttps://api.ironflock.com/mcp
URL su un Appliancehttps://api. seguito dal dominio dell’Appliance, poi /mcp, non appena l’Appliance esegue il servizio API IronFlock
TrasportoStreamable HTTP
AutenticazioneAuthorization: Bearer <your API key>

Crea la chiave API in Studio come descritto in Creare una Chiave API. Ogni richiesta porta con sé la chiave. Una richiesta senza chiave, o con una chiave non valida (eliminata, scaduta o di un altro IronFlock), riceve HTTP 401. Il server non offre l’accesso tramite browser (OAuth): la chiave è l’unico modo per entrare.

Il server non mantiene sessioni. Ogni richiesta riceve una risposta a sé, quindi un client può connettersi, disconnettersi e riconnettersi liberamente. Risponde a ogni richiesta con un unico corpo JSON e non ha alcun flusso di eventi da ascoltare.

Collegare Claude

La chiave la inserisci tu, nelle impostazioni di Claude. Non incollarla mai in una chat.

Claude Code

Claude Code si collega tramite il plugin ironflock, che dichiara il server MCP di IronFlock. Funziona nel terminale, nelle estensioni per IDE e nella scheda Code dell’app desktop di Claude.

  1. Aggiungi il marketplace e installa il plugin in una sessione di Claude Code:

    /plugin marketplace add IronFlock/agent-skills /plugin install ironflock@ironflock
  2. L’installazione apre una finestra di dialogo con due impostazioni. IronFlock API address è https://api.ironflock.com per il cloud, e https://api. seguito dal dominio dell’Appliance per un Appliance, in entrambi i casi senza /mcp e senza barra finale. IronFlock API key è la chiave di Studio. Claude Code la conserva nell’archivio sicuro delle credenziali del sistema, non in un file di impostazioni.

  3. Riavvia Claude Code. A quel punto /mcp elenca il server plugin:ironflock:ironflock come connesso.

Modifica le impostazioni in seguito con /plugin configure ironflock@ironflock, e riavvia Claude Code. Finché la chiave non è impostata, il server non si avvia. Un’installazione da una shell (claude plugin install) non apre la finestra di dialogo, quindi completala con /plugin configure ironflock@ironflock in una sessione. Sviluppare con Claude Code descrive i plugin e le loro skill.

Claude sul Web, sul Desktop e sul Telefono, e Cowork

La connessione propria del plugin funziona solo in Claude Code. Nella chat dell’app Claude e in Cowork aggiungi IronFlock una volta come connettore personalizzato, con la chiave come header della richiesta. Gli header della richiesta nei connettori personalizzati sono una beta disponibile per un numero limitato di organizzazioni. Se la finestra di dialogo qui sotto non ha la sezione Request headers, la tua organizzazione non ce l’ha ancora, e per ora IronFlock non può essere collegato lì: Claude Code funziona.

  1. Apri Customize > Connectors, scegli Add, poi Add custom connector.
  2. Inserisci il nome IronFlock e l’URL del server https://api.ironflock.com/mcp.
  3. Imposta Authentication su No sign-in.
  4. In Request headers, aggiungi l’header Authorization con il valore Bearer seguito dalla tua chiave: la parola Bearer, uno spazio, poi la chiave. Senza Bearer IronFlock rifiuta la richiesta.
  5. Scegli Add.

Nei piani Team ed Enterprise un owner aggiunge il connettore in Organization settings > Connectors, Add, poi Custom; gli header della richiesta possono trovarsi in Advanced. Tutti quelli che usano quel connettore agiscono con l’unica chiave inserita dall’owner, quindi assegnale solo le autorizzazioni e i progetti che tutti loro possono usare.

Gli header della richiesta di un connettore non possono essere modificati: per cambiare la chiave, rimuovi il connettore e aggiungilo di nuovo. Il connettore si collega dai server di Anthropic, quindi l’indirizzo deve essere raggiungibile da internet. È il caso del cloud. Un Appliance raggiungibile solo dalla rete della tua azienda di solito non può essere collegato lì, mentre Claude Code su un computer in quella rete sì.

Altri Client MCP

Qualsiasi client che supporti Streamable HTTP e un header della richiesta si collega con l’URL e l’header Authorization: Bearer <your API key>. Tieni la chiave fuori dai file che condividi o di cui fai il commit.

Verificare la Connessione

Chiedi a Claude di elencare i tuoi progetti IronFlock, poi i dispositivi di uno di essi. Claude chiama list_projects e list_devices, che si limitano a leggere.

Strumenti

Il server offre 33 strumenti in queste aree. La maggior parte lavora in un progetto e riceve il suo swarm_key, che list_projects fornisce. Uno strumento che modifica o elimina qualcosa è contrassegnato come tale, così che client come Claude possano chiederti conferma prima di chiamarlo.

Progetti

StrumentoAutorizzazioneCosa fa
list_projectsdevices:readElenca i progetti in cui la chiave può lavorare

Dispositivi

StrumentoAutorizzazioneCosa fa
list_devicesdevices:readElenca i dispositivi di un progetto, le app installate su ciascuno, se sono in esecuzione e se il dispositivo è online
create_devicedevices:writeCrea un dispositivo nel progetto e risponde con la sua chiave e il suo nome
delete_devicedevices:writeElimina definitivamente un dispositivo dal progetto

App in un Progetto

StrumentoAutorizzazioneCosa fa
list_project_appsapps:readElenca le app installate nel progetto e su quanti dispositivi è in esecuzione ciascuna
check_app_statusapps:readMostra se un’app è in esecuzione sui suoi dispositivi e se i suoi dati arrivano
install_appapps:writeInstalla un’app dello store nel progetto e, facoltativamente, sui dispositivi
set_app_stateapps:writeAvvia o arresta un’app installata sui dispositivi
update_appapps:writeAggiorna un’app installata alla sua release più recente
uninstall_appapps:writeRimuove un’app dai dispositivi, o dall’intero progetto

App Store e Costi

StrumentoAutorizzazioneCosa fa
search_appsapps:readCerca nell’app store per funzionalità e restituisce le app corrispondenti con i loro prezzi
get_app_detailsapps:readLegge la descrizione, il README e il prezzo di una fino a tre app dello store
get_install_quoteapps:readVerifica quanto costerebbe installare un’app e cosa lo impedirebbe
estimate_project_costapps:readStima il costo annuale di una configurazione di progetto; non si acquista nulla
sync_app_to_storeapps:writeSolo su un Appliance: copia un’app dello store del cloud IronFlock nello store dell’Appliance

Dati

StrumentoAutorizzazioneCosa fa
get_schemadata:readDescrive il database del progetto: le sue tabelle, viste e colonne
execute_sqldata:readEsegue una query SELECT di sola lettura sul database del progetto
list_dashboardsdata:readElenca le dashboard del progetto
list_app_filesdata:readElenca e cerca i file che un’app memorizza nel progetto
read_app_filedata:readLegge un file memorizzato da un’app: testo, un’immagine o un altro file
save_transformdata:writeCrea o sostituisce una trasformazione personalizzata che mantiene aggiornato un valore derivato per le board
delete_transformdata:writeElimina definitivamente una trasformazione personalizzata

Allarmi

StrumentoAutorizzazioneCosa fa
list_alarmsalarms:readElenca gli allarmi del progetto con il loro stato, i trigger e i destinatari
create_alarmalarms:writeCrea un allarme che sorveglia una tabella dati di un’app
update_alarmalarms:writeModifica il trigger o i destinatari di un allarme, oppure lo mette in pausa e lo riprende
delete_alarmalarms:writeElimina definitivamente un allarme e la sua cronologia

Log e Registro di Audit

StrumentoAutorizzazioneCosa fa
get_app_logslogs:readLegge l’output di log di un’app dai dispositivi su cui è in esecuzione
get_device_logslogs:readLegge cosa ha fatto il dispositivo stesso: app, download, disco, rete, aggiornamenti dell’agente
query_audit_loglogs:readEsegue una query di sola lettura sul registro di audit: chi ha modificato il progetto, i suoi dispositivi, gruppi e app, e quando
get_appliance_healthdevices:readSolo su un Appliance: verifica lo stato dei servizi di piattaforma dell’Appliance, del disco, della memoria, della licenza e degli aggiornamenti
get_appliance_logslogs:readSolo su un Appliance: legge il log di una parte della piattaforma dell’Appliance

Strumenti delle App

Le app portano strumenti propri con i loro agenti AI: funzioni dell’app che vengono eseguite su un dispositivo, come leggere lo stato di una macchina o modificare un’impostazione. Due strumenti li raggiungono.

StrumentoAutorizzazioneCosa fa
list_app_toolsapptools:callElenca gli strumenti di un’app installata, con i loro argomenti e le istruzioni degli agenti dell’app
call_app_toolapptools:callEsegue uno di essi su un dispositivo del progetto

call_app_tool viene eseguito su un dispositivo, e uno strumento di un’app può modificare cose lì. Il dispositivo deve essere uno dei dispositivi del progetto che il proprietario della chiave può vedere, e il proprietario deve avere il diritto di usare i dati dell’app, come quando usa l’app dalla sua board. L’app riceve esattamente gli argomenti indicati e nient’altro. Vengono elencati solo gli strumenti della release installata, non quelli della versione di sviluppo di un’app. I testi di uno strumento sono scritti dallo sviluppatore dell’app e vengono troncati a una lunghezza fissa.

Autorizzazioni

Ogni strumento richiede l’autorizzazione indicata nelle tabelle sopra. Il server offre a un client solo gli strumenti che la chiave può usare, e rifiuta ogni altro strumento come se non esistesse. Qualunque cosa consenta la chiave, uno strumento non fa mai più di quanto il proprietario della chiave possa fare in IronFlock. releases:publish non ha uno strumento: serve per le operazioni REST che compilano le release. Vedi Autorizzazioni per l’elenco completo, e Creare una Chiave API per come sceglierle in Studio.

Una chiave limitata a dei progetti vede solo quei progetti. A una chiave limitata a un’app vengono offerti solo gli strumenti che agiscono per un’app, quindi non list_projects. A nessuna delle due vengono offerti gli strumenti che vanno oltre un progetto: query_audit_log, la cui query può nominare risorse di qualsiasi progetto che il proprietario può leggere, i due strumenti dell’Appliance, che non appartengono a nessun progetto, e sync_app_to_store, che modifica lo store dell’Appliance per tutti.

Alcuni strumenti hanno regole aggiuntive:

  • install_app riceve la risposta di get_install_quote che ti è stata mostrata, e non installa nulla se da allora il prezzo o qualsiasi altro elemento di quel preventivo è cambiato. Installare un’app a pagamento costa denaro.
  • set_app_state e update_app modificano al massimo 10 dispositivi in una chiamata.
  • create_device risponde con la chiave e il nome del nuovo dispositivo, e mai con il suo file di configurazione, che contiene le credenziali del dispositivo. Scarica il file in Studio, nelle impostazioni del dispositivo, in Manutenzione > File di configurazione dispositivo > Scarica file di configurazione, oppure configura il dispositivo sulla macchina con ironflock agent install --project <project> --name <name>, che crea il dispositivo e conserva il file sulla macchina (Login e gestione dei dispositivi).
  • Un progetto salva una trasformazione personalizzata alla volta. Un secondo save_transform mentre il primo è in esecuzione viene rifiutato.
  • Un account può eseguire query_audit_log una volta alla volta e sei volte al minuto, perché il database sottostante è condiviso.
  • Una modifica che non termina entro il tempo della sua chiamata potrebbe comunque essere eseguita. Il risultato lo dice, e lo strumento non la ripete.

Risultati

Un risultato è JSON, come contenuto strutturato e come lo stesso JSON in un blocco di testo. Un elenco lungo viene tagliato per stare in 50.000 caratteri, e il suo membro cut dice quante voci sono state omesse e come continuare a leggere. Le immagini (PNG, JPEG, GIF e WebP) arrivano come immagini, e gli altri file, come un PDF, come risorse incorporate con il loro tipo di media.

Quando uno strumento non può fare ciò che è stato chiesto, il suo risultato viene contrassegnato come errore e dice perché in una frase, ad esempio che un progetto non esiste o che la piattaforma non ha risposto in tempo.

Limiti

Questi sono i valori predefiniti, per chiave API:

Limite
Richieste120 al minuto, a raffiche di massimo 30
Richieste aperte contemporaneamente8
Corpo della richiesta1.114.112 byte: 1 MiB di argomenti e il messaggio che li contiene
Una chiamata a uno strumento90 secondi
Una query al database30 secondi; execute_sql risponde con 100 righe a meno che tu non ne chieda di più, al massimo 1.000
Un risultato50.000 caratteri; il risultato di call_app_tool viene tagliato a 45.000

Errori

RispostaSignificatoCosa fare
401La chiave manca, è digitata male o troncata, eliminata, scaduta o di un altro IronFlock. In un connettore può mancare Bearer Crea una nuova chiave nello Studio dell’IronFlock a cui ti colleghi e inseriscila di nuovo
404 su /mcp/mcp compare due volte nell’indirizzo, oppure l’istanza non offre ancora l’endpoint, come un Appliance che non esegue il servizio API IronFlockCorreggi l’indirizzo; altrimenti usa il cloud
405GET e DELETE su /mcp: il server non ha flusso di eventi né sessione da chiudereUsa POST
413Il corpo della richiesta è troppo grandeInvia meno dati in una chiamata
429La chiave ha fatto troppe richieste, o ne ha troppe aperte contemporaneamente. L’header Retry-After dice quanti secondi attendereAttendi quel tempo, poi continua con meno chiamate contemporanee
503La piattaforma non è disponibile al momento, oppure il servizio si sta arrestandoRiprova tra un minuto
504La piattaforma non ha risposto in tempoRiprova tra un minuto

Uno strumento che non può fare ciò che è stato chiesto non risponde con un errore HTTP: il suo risultato viene contrassegnato come errore e spiega in una frase cosa è andato storto.

Proteggere la Tua Chiave

  • Non incollare mai una chiave in una chat. Se l’hai fatto, fa parte di quella conversazione: elimina la chiave in Studio, creane una nuova e inseriscila nelle impostazioni.
  • Studio mostra una nuova chiave solo una volta, quando la crei. Salvala subito nelle impostazioni del client.
  • Usa una chiave per ogni posto che la usa, così puoi eliminarne una senza compromettere le altre, ed elimina le chiavi che non usi più. Una chiave è valida per un anno.
  • Dai a una chiave solo le autorizzazioni e i progetti di cui Claude ha bisogno: una chiave che può fare Tutto in Tutti i miei progetti permette a Claude di fare tutto ciò che puoi fare tu in IronFlock. Gli strumenti che modificano o eliminano qualcosa sono contrassegnati come tali, così che client come Claude possano chiederti conferma prima. Leggi cosa Claude sta per modificare prima di acconsentire.
  • Un connettore condiviso da un’organizzazione agisce con una sola chiave per tutti i suoi utenti. Usa una chiave di un account che può vedere solo ciò che tutti loro possono vedere.
Last updated on