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 IronFlock | https://api.ironflock.com/mcp |
| URL su un Appliance | https://api. seguito dal dominio dell’Appliance, poi /mcp, non appena l’Appliance esegue il servizio API IronFlock |
| Trasporto | Streamable HTTP |
| Autenticazione | Authorization: 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.
-
Aggiungi il marketplace e installa il plugin in una sessione di Claude Code:
/plugin marketplace add IronFlock/agent-skills /plugin install ironflock@ironflock -
L’installazione apre una finestra di dialogo con due impostazioni. IronFlock API address è
https://api.ironflock.comper il cloud, ehttps://api.seguito dal dominio dell’Appliance per un Appliance, in entrambi i casi senza/mcpe 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. -
Riavvia Claude Code. A quel punto
/mcpelenca il serverplugin:ironflock:ironflockcome 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.
- Apri Customize > Connectors, scegli Add, poi Add custom connector.
- Inserisci il nome
IronFlocke l’URL del serverhttps://api.ironflock.com/mcp. - Imposta Authentication su No sign-in.
- In Request headers, aggiungi l’header
Authorizationcon il valoreBearerseguito dalla tua chiave: la parola Bearer, uno spazio, poi la chiave. SenzaBearerIronFlock rifiuta la richiesta. - 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
| Strumento | Autorizzazione | Cosa fa |
|---|---|---|
list_projects | devices:read | Elenca i progetti in cui la chiave può lavorare |
Dispositivi
| Strumento | Autorizzazione | Cosa fa |
|---|---|---|
list_devices | devices:read | Elenca i dispositivi di un progetto, le app installate su ciascuno, se sono in esecuzione e se il dispositivo è online |
create_device | devices:write | Crea un dispositivo nel progetto e risponde con la sua chiave e il suo nome |
delete_device | devices:write | Elimina definitivamente un dispositivo dal progetto |
App in un Progetto
| Strumento | Autorizzazione | Cosa fa |
|---|---|---|
list_project_apps | apps:read | Elenca le app installate nel progetto e su quanti dispositivi è in esecuzione ciascuna |
check_app_status | apps:read | Mostra se un’app è in esecuzione sui suoi dispositivi e se i suoi dati arrivano |
install_app | apps:write | Installa un’app dello store nel progetto e, facoltativamente, sui dispositivi |
set_app_state | apps:write | Avvia o arresta un’app installata sui dispositivi |
update_app | apps:write | Aggiorna un’app installata alla sua release più recente |
uninstall_app | apps:write | Rimuove un’app dai dispositivi, o dall’intero progetto |
App Store e Costi
| Strumento | Autorizzazione | Cosa fa |
|---|---|---|
search_apps | apps:read | Cerca nell’app store per funzionalità e restituisce le app corrispondenti con i loro prezzi |
get_app_details | apps:read | Legge la descrizione, il README e il prezzo di una fino a tre app dello store |
get_install_quote | apps:read | Verifica quanto costerebbe installare un’app e cosa lo impedirebbe |
estimate_project_cost | apps:read | Stima il costo annuale di una configurazione di progetto; non si acquista nulla |
sync_app_to_store | apps:write | Solo su un Appliance: copia un’app dello store del cloud IronFlock nello store dell’Appliance |
Dati
| Strumento | Autorizzazione | Cosa fa |
|---|---|---|
get_schema | data:read | Descrive il database del progetto: le sue tabelle, viste e colonne |
execute_sql | data:read | Esegue una query SELECT di sola lettura sul database del progetto |
list_dashboards | data:read | Elenca le dashboard del progetto |
list_app_files | data:read | Elenca e cerca i file che un’app memorizza nel progetto |
read_app_file | data:read | Legge un file memorizzato da un’app: testo, un’immagine o un altro file |
save_transform | data:write | Crea o sostituisce una trasformazione personalizzata che mantiene aggiornato un valore derivato per le board |
delete_transform | data:write | Elimina definitivamente una trasformazione personalizzata |
Allarmi
| Strumento | Autorizzazione | Cosa fa |
|---|---|---|
list_alarms | alarms:read | Elenca gli allarmi del progetto con il loro stato, i trigger e i destinatari |
create_alarm | alarms:write | Crea un allarme che sorveglia una tabella dati di un’app |
update_alarm | alarms:write | Modifica il trigger o i destinatari di un allarme, oppure lo mette in pausa e lo riprende |
delete_alarm | alarms:write | Elimina definitivamente un allarme e la sua cronologia |
Log e Registro di Audit
| Strumento | Autorizzazione | Cosa fa |
|---|---|---|
get_app_logs | logs:read | Legge l’output di log di un’app dai dispositivi su cui è in esecuzione |
get_device_logs | logs:read | Legge cosa ha fatto il dispositivo stesso: app, download, disco, rete, aggiornamenti dell’agente |
query_audit_log | logs:read | Esegue una query di sola lettura sul registro di audit: chi ha modificato il progetto, i suoi dispositivi, gruppi e app, e quando |
get_appliance_health | devices:read | Solo su un Appliance: verifica lo stato dei servizi di piattaforma dell’Appliance, del disco, della memoria, della licenza e degli aggiornamenti |
get_appliance_logs | logs:read | Solo 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.
| Strumento | Autorizzazione | Cosa fa |
|---|---|---|
list_app_tools | apptools:call | Elenca gli strumenti di un’app installata, con i loro argomenti e le istruzioni degli agenti dell’app |
call_app_tool | apptools:call | Esegue 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_appriceve la risposta diget_install_quoteche 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_stateeupdate_appmodificano al massimo 10 dispositivi in una chiamata.create_devicerisponde 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 conironflock 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_transformmentre il primo è in esecuzione viene rifiutato. - Un account può eseguire
query_audit_loguna 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 | |
|---|---|
| Richieste | 120 al minuto, a raffiche di massimo 30 |
| Richieste aperte contemporaneamente | 8 |
| Corpo della richiesta | 1.114.112 byte: 1 MiB di argomenti e il messaggio che li contiene |
| Una chiamata a uno strumento | 90 secondi |
| Una query al database | 30 secondi; execute_sql risponde con 100 righe a meno che tu non ne chieda di più, al massimo 1.000 |
| Un risultato | 50.000 caratteri; il risultato di call_app_tool viene tagliato a 45.000 |
Errori
| Risposta | Significato | Cosa fare |
|---|---|---|
401 | La 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 IronFlock | Correggi l’indirizzo; altrimenti usa il cloud |
405 | GET e DELETE su /mcp: il server non ha flusso di eventi né sessione da chiudere | Usa POST |
413 | Il corpo della richiesta è troppo grande | Invia meno dati in una chiamata |
429 | La chiave ha fatto troppe richieste, o ne ha troppe aperte contemporaneamente. L’header Retry-After dice quanti secondi attendere | Attendi quel tempo, poi continua con meno chiamate contemporanee |
503 | La piattaforma non è disponibile al momento, oppure il servizio si sta arrestando | Riprova tra un minuto |
504 | La piattaforma non ha risposto in tempo | Riprova 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.