Server MCP

Il Model Context Protocol è lo standard con cui assistenti come Claude o ChatGPT chiamano strumenti esterni. Il nostro server risponde su https://flyitalyadsb.com/mcp (Streamable HTTP) con questi strumenti:

Strumento	Cosa fa
find_aircraft	un aereo in volo per hex ICAO, nominativo (va bene anche il numero di volo) o immatricolazione; se non vola, il suo ultimo volo osservato
aircraft_near	tutti gli aerei in un raggio da un punto, o da un aeroporto italiano per nome
special_traffic	traffico militare, PIA o LADD
observed_flights	lo storico voli, cioè i voli che la rete ha visto: le rotte abituali di un nominativo, il registro dei voli di un aereo, le partenze o gli arrivi di un aeroporto in un giorno; su Fleet anche i voli di oggi di un nominativo o di un aereo
aircraft_history	le date con storico di un aereo, o la sua traccia in un giorno
aircraft_profile	quello che sappiamo di un aereo: identità, stato live, riepilogo dello storico, link a mappa e foto
overflights	gli aerei passati sopra un luogo (coordinate, aeroporto o la tua posizione) tra due istanti
notable_traffic	le emergenze e gli aerei particolari (squawk di emergenza, militari) in una zona nelle ultime ore
watched_aircraft	elenca, aggiunge o toglie i tuoi aerei seguiti; per aggiungere serve Fleet (fino a 25)
fleet_status	i voli di oggi di ogni aereo seguito: stato dell’ultimo volo, ultimo aeroporto, arrivo stimato se è in volo; Fleet
set_my_location	salva la tua posizione sull’account, per «vicino a me»
clear_my_location	la cancella

La pagina MCP e agenti AI ha gli stessi passi con le schermate della mappa in chat e una domanda di esempio per ogni strumento.

Collegarlo a Claude

1. Su claude.ai apri Connettori e scegli Aggiungi connettore personalizzato.
2. Nome FlyItalyADSB, URL https://flyitalyadsb.com/mcp.
3. Premi Connetti: scrivi la tua email, il codice di 6 cifre che ti arriva, e premi Consenti. Se non hai una chiave, ne viene creata una gratuita.
4. Chiedi per esempio: “che aerei ci sono ora vicino a Fiumicino?”

Lo scolleghi da La mia API.

Vicino a me

Nessun assistente passa al server la posizione del tuo telefono o del tuo computer. Per chiedere «che aerei ci sono vicino a me?» senza dire dove sei, salva una posizione una volta:

• da La mia API, con Usa la mia posizione;
• oppure dicendola all’assistente: «la mia posizione è Brescia».

La salviamo arrotondata a circa 1 km, una sola per account, e la cancelli quando vuoi («dimentica la mia posizione» o da La mia API). Su ChatGPT, se non ne hai salvata una, usiamo la città che ChatGPT allega alla richiesta.

La tua flotta (Fleet)

Su Fleet gestisci i tuoi aerei seguiti dalla chat («segui EI-DAC come Ops 1») e chiedi dove sono oggi («dov’è la mia flotta?», «EI-DAC è atterrato?»). fleet_status risponde dai decolli e dagli atterraggi di oggi rilevati in tempo reale: per ogni aereo l’ultimo volo, l’ultimo aeroporto e, per un aereo in volo adesso, un orario di arrivo stimato, che è una stima e mai un orario di linea. Un decollo o un atterraggio che la rete non vede manca.

Gli avvisi di decollo e atterraggio sono un webhook che crei una volta con l’API: nessuno strumento lo crea, perché il suo segreto di firma si vede una volta sola e non deve passare da una chat.

La mappa in chat

Su Claude (web, desktop e app) e su ChatGPT, aircraft_near, special_traffic e find_aircraft mostrano il risultato anche su una mappa dentro la conversazione: gli aerei colorati per quota, l’area della ricerca, un elenco da ordinare e i dettagli dell’aereo che tocchi. Gli altri client ricevono gli stessi dati come testo.

Intorno a un luogo o a un aereo, la mappa mostra tutto il traffico dell’area che inquadri, non solo il risultato della domanda: spostala o cambia lo zoom e carica gli aerei della nuova area. Carica al massimo un cerchio di 500 km: con una vista più ampia mostra il centro e ti chiede di ingrandire. Il traffico militare, PIA o LADD resta quella ricerca, su tutta la rete.

«Live» è acceso da subito: aggiorna la mappa ogni 3 secondi, solo mentre è sullo schermo, e si mette in pausa dopo 10 minuti senza che la tocchi; toccarla lo riaccende, e il pulsante lo spegne. Tra un aggiornamento e l’altro gli aerei in volo si muovono secondo rotta e velocità: è una stima, e dopo un minuto senza dati nuovi si fermano e diventano sbiaditi. Ogni aggiornamento e ogni spostamento della mappa contano come una richiesta: Live acceso fa 20 richieste al minuto. «Aggiorna» carica subito i dati nuovi.

La mappa carica solo le tessere di OpenStreetMap, non chiede permessi e non usa la tua posizione. Mappa © contributori di OpenStreetMap; dati degli aerei © FlyItalyADSB, CC BY-SA 4.0.

Claude Code e client senza OAuth

Con la tua chiave nell’header:

claude mcp add --transport http flyitalyadsb https://flyitalyadsb.com/mcp \
  --header "X-Api-Key: LA_TUA_CHIAVE"

Gli altri client MCP con OAuth si collegano con Connetti, come Claude. Gli agenti che conoscono solo la tua email possono usare la registrazione auth.md.

Limiti

Ogni chiamata a uno strumento è una richiesta all’API e conta sul piano della tua chiave, come una chiamata diretta. Anche il raggio massimo è quello del piano. Due eccezioni: watched_aircraft non si conta, e fleet_status conta una richiesta per ogni aereo seguito che controlla (due per una voce che può essere un’immatricolazione o un nominativo).