Dev Mode in ChatGPT: colleghiamo un'app locale

1. Che cos'è il Developer Mode «sul serio»

Del Dev Mode sai già qualcosa, ma ora è importante comporre un quadro completo basato sulla pratica reale.

Il Developer Mode in ChatGPT è una modalità speciale in cui la piattaforma permette di collegare la tua app direttamente, senza pubblicarla nello Store. Dici a ChatGPT: «Ecco l'URL del mio server MCP», e ChatGPT lo tratta come uno strumento esterno con UI — può chiamarne gli strumenti, caricare widget, e tutto questo nel contesto di una normale chat.

Se ricordiamo l'architettura, in Dev Mode ChatGPT agisce come client MCP, mentre il tuo template Next.js — come server MCP. ChatGPT stabilisce una connessione a /mcp, chiede: «Che cosa sai fare?» (elenco di tools e resources) e poi, nel corso del dialogo, può invocare questi strumenti e mostrare i tuoi widget in un iframe.

È importante distinguere il Dev Mode dallo Store:

• Dev Mode — il tuo piccolo «garage» personale: puoi rompere, sperimentare, cambiare lo schema degli strumenti ogni cinque minuti, senza preoccuparti degli utenti.
• Store — la vetrina: ci finisce una versione stabile, dopo review e con policy, descrizioni, ecc. Ci arriveremo alla fine del corso, per ora giochiamo nel garage.

A fine 2025 il Dev Mode con Apps SDK è disponibile in tutti i piani di ChatGPT, ma negli account aziendali a volte serve che un amministratore lo abiliti a livello di workspace. Se nelle impostazioni non compare l'interruttore Developer Mode, questo è il primo punto da verificare.

2. Cosa abbiamo già all'inizio della lezione

Prima di cliccare qualcosa nell'interfaccia di ChatGPT, assicuriamoci che la parte locale sia pronta.

Per prima cosa, il dev server di Next.js. Nella root del progetto hai già avviato:

npm run dev

Per impostazione predefinita Next.js 16 ascolta sulla porta 3000, quindi la tua UI è disponibile all'indirizzo http://localhost:3000.

In secondo luogo, la route MCP. Nel template CodeGym Labs il server MCP è implementato come route handler app/mcp/route.ts. Proprio in questo file si registrano strumenti e risorse; ed è lì che arriveranno le prime richieste da ChatGPT quando colleghi l'app in Dev Mode.

Dal punto di vista architetturale ora è tutto così:

Il tuo browser ──> http://localhost:3000 (Next.js dev, UI)
                           │
                           └── /mcp (server MCP dentro Next.js)

Per ora non c'è alcun collegamento con ChatGPT — vive nel cloud e il tuo localhost non è visibile. La configurazione dettagliata del tunnel sarà oggetto della lezione successiva. Qui, per semplicità, supponiamo che tu abbia già un qualsiasi URL HTTPS pubblico verso /mcp (ad esempio tramite ngrok o Cloudflare Tunnel, configurato secondo il README del template).

Se non hai ancora alzato il tunnel — nessun problema. Ora passerai comunque con gli occhi l'intera catena di passi nel Dev Mode e vedrai esattamente che cosa dovrai fare quando avrai l'URL HTTPS.

Se hai già un URL HTTPS verso /mcp, puoi ripetere tutti i passaggi a mano.
Se ancora non ce l'hai — segui la lezione come «tour dell'interfaccia»: è importante capire la sequenza dei passi, e l'esecuzione reale la faremo nella prossima lezione, quando configureremo il tunnel.

3. Attiviamo il Developer Mode nell'interfaccia di ChatGPT

Il primo passo è semplicemente far sì che ChatGPT mostri le impostazioni giuste. Fai così:

Accedi alla versione web di ChatGPT con l'account con cui svilupperai. Clicca sull'icona del profilo nell'angolo in basso a sinistra (o in alto a destra — l'UI evolve continuamente) e scegli Settings (Impostazioni).

Nelle impostazioni trova la sezione relativa alle app: di solito si chiama Apps & Connectors o Connected apps. Aprila. In fondo alla pagina (o nella scheda Advanced / Avanzate) comparirà l'interruttore Developer Mode. È proprio quello che devi attivare.

Dopo l'attivazione del Dev Mode, ChatGPT in genere mostra una notifica che il modo sviluppatore è abilitato. Nella stessa sezione compare un pulsante del tipo Create, Create connector, New app — le diciture possono variare, ma l'idea è una: è apparso un modo per creare la tua app collegata.

Se nelle impostazioni non c'è né la sezione Apps & Connectors né l'interruttore Developer Mode, verifica:

• di essere effettivamente loggato nell'account ChatGPT che vuoi usare;
• negli account aziendali questa modalità può essere abilitata dall'amministratore del workspace.

A volte basta semplicemente uscire e rientrare (il classico «stacca e riattacca Internet» applicato al Dev Mode).

4. Creiamo la nostra app / connettore e indichiamo l'MCP URL

Ora che il Dev Mode è attivo, registriamo il tuo GiftGenius in ChatGPT. Di seguito — lo scenario «come farlo sul serio». Se l'URL HTTPS non è ancora configurato, considera i passi come una prova a secco: osserva semplicemente che cosa faremo quando il tunnel sarà pronto.

Si fa tutto attraverso la sezione impostazioni di ChatGPT, dove eri poco fa. La sequenza sarà più o meno questa.

Apri di nuovo Settings → Apps & Connectors. All'interno vedrai l'elenco delle app già collegate (probabilmente vuoto) e il pulsante Create / Add connector. Cliccalo — si aprirà il form di creazione dell'app.

Il form di solito ha tre campi chiave:

1. Nome (Name). È il nome leggibile che sarà visibile sia a te sia a ChatGPT. Per il nostro corso è comodo chiamare l'app, ad esempio, GiftGenius (dev) — così è subito chiaro che è la versione dev locale.
2. Descrizione (Description). Una breve spiegazione di cosa fa l'app e quando usarla. Esempio: «Suggerisce idee regalo in base agli interessi della persona». Questa stringa influisce poi sul discovery — il modello la usa per decidere quando proporre il tuo App in chat.
3. URL del server MCP (talvolta etichettato come Connector URL, MCP endpoint, App URL, ecc.). È il campo più importante: qui incolli l'URL HTTPS pubblico che punta a /mcp della tua app.

Ad esempio:

https://my-giftgenius-dev.ngrok.app/mcp

oppure

https://giftgenius-dev.trycloudflare.com/mcp

Principali finezze per questo campo:

• obbligatorio https://, altrimenti ChatGPT rifiuterà la connessione;
• obbligatorio il percorso /mcp alla fine, perché è lì che «vive» il server MCP dentro il template; ed è proprio questo percorso a essere descritto nella documentazione ufficiale dell'Apps SDK.

Da dove prendere questo URL, lo vedremo nel dettaglio nella prossima lezione (tunnel, Cloudflare, ngrok). Ora è importante l'idea: il tuo http://localhost:3000/mcp locale deve in qualche modo diventare un https://…/mcp pubblico, e questo indirizzo pubblico è quello che inserisci nel form.

Dopo aver compilato i campi, premi Create / Salva. In questo momento ChatGPT fa un «handshake» con il tuo server: invia richieste HTTP all'URL indicato, si aspetta di ricevere un manifesto delle capacità (elenco di tools/resources, metadati) e verifica che il server risponda secondo il protocollo MCP. Se tutto va bene, il connettore apparirà nell'elenco e vedrai quali strumenti ha trovato ChatGPT. Nel prossimo capitolo analizzeremo che cosa succede esattamente in questo handshake e come vederlo nei log.

Se non hai ancora configurato il tunnel e hai incollato un URL fittizio, ChatGPT ti dirà onestamente che non è riuscito a raggiungere il server. Anche questo è utile: vedrai subito dove e come vengono mostrate le error.

5. Cosa succede «sotto il cofano»: handshake MCP spiegato semplice

Da fuori sembra un normale form «aggiungi un'app tramite URL». Dentro è un po' più interessante, e capirlo ora torna utile per il debug.

Hai già visto che durante la creazione del connettore ChatGPT va sul tuo /mcp e si aspetta un manifesto. Vediamo ora la conversazione un po' più in dettaglio — aiuta molto in fase di debugging.

Quando premi il pulsante Create, ChatGPT compie alcuni passi.

Per prima cosa contatta l'URL indicato con /mcp, agendo come client MCP. Secondo il protocollo MCP si aspetta che su quell'endpoint HTTP ci sia un server che implementa le capacità di base: elencare gli strumenti (list tools), fornire risorse (widget), gestire le chiamate agli strumenti.

Il server, a sua volta, risponde con una struttura JSON che descrive:

• nome del server e versione;
• elenco degli strumenti: name, title, description, inputSchema, ecc.;
• elenco delle risorse: dove prendere l'HTML dei tuoi widget, quali MIME types, come renderizzarli.

Nel template Next.js di CodeGym tutto questo è già implementato in app/mcp/route.ts: lì, usando l'SDK, si invoca qualcosa come server.registerTool(...) e server.registerResource(...).

Se vuoi vedere questo handshake con i tuoi occhi, puoi aggiungere in app/mcp/route.ts un semplice log. È più che altro un trucco di debug per sviluppatori, puoi saltarlo e tornarci più tardi, quando vorrai scavare più a fondo:

// app/mcp/route.ts
import { NextRequest, NextResponse } from "next/server";
// importa il tuo server / buildManifest già esistente

export async function GET(req: NextRequest) {
  console.log("[MCP] Handshake from ChatGPT:", req.headers.get("user-agent"));
  const manifest = buildManifestSomehow(); // questo è già presente nel template
  return NextResponse.json(manifest);
}

Questa funzione è un po' indicativa (nel template la struttura può differire), ma l'idea è semplice: app/mcp/route.ts è un normale route handler di Next.js e puoi loggare le richieste in ingresso. In caso di collegamento riuscito in Dev Mode vedrai questo log nel terminale dove gira npm run dev.

Dal punto di vista del protocollo si può disegnare come un piccolo diagramma:

sequenceDiagram
    participant ChatGPT
    participant Tunnel as HTTPS URL (/mcp)
    participant NextDev as Next.js dev + MCP

    ChatGPT->>Tunnel: richiesta HTTP(S) a https://.../mcp
    Tunnel->>NextDev: proxy verso http://localhost:3000/mcp
    NextDev-->>Tunnel: JSON con strumenti e risorse
    Tunnel-->>ChatGPT: inoltra la risposta
    ChatGPT->>ChatGPT: mette in cache l'elenco di tools/resources

Il fatto che nel form del Dev Mode tu abbia inserito «solo un URL» in realtà avvia un'intera conversazione di protocollo.

6. Come ChatGPT «vede» la tua app dopo il collegamento

Supponiamo che l'handshake sia andato a buon fine. E ora?

Per prima cosa, nelle impostazioni nella sezione Apps & Connectors il tuo GiftGenius (dev) comparirà nell'elenco delle app collegate. Nella card vedrai nome, descrizione ed elenco degli strumenti rilevati. Di solito ci sono anche pulsanti come Refresh, Delete, ecc. Il pulsante Refresh tornerà utile più avanti, quando cambierai lo schema degli strumenti.

In secondo luogo, l'app diventa disponibile nelle chat. Apri una nuova chat, clicca sul pulsante «+» accanto al campo di input. C'è un menu «More», «Apps», «Tools» — a seconda della versione attuale dell'UI. Il tuo GiftGenius (dev) dovrebbe apparire nell'elenco e puoi selezionarlo esplicitamente per questa conversazione.

Dopo la selezione, l'app diventa «collegata» a quella chat. Per te si presenta così:

• scrivi una richiesta naturale, ad esempio: «Scegli un regalo per un fan dello spazio da 50$»;
• ChatGPT decide (in base alla descrizione e alla cronologia del dialogo) che può usare GiftGenius e invoca uno dei tuoi strumenti MCP;
• il risultato di questa invocazione può contenere un widget HTML; questo viene renderizzato direttamente in chat come card/pannello.

In Dev Mode, spesso inizialmente chiamerai l'app in modo esplicito — tramite selezione nel menu o menzione esplicita per nome. Ma è importante capire: in produzione ChatGPT può «proporre» automaticamente la tua App, basandosi sulla sua descrizione e sui metadati degli strumenti.

Per chiarezza, è utile immaginare ancora una tabella:

7. Ciclo di sviluppo: cambio codice → vedo in ChatGPT

Collegare un'App è metà dell'opera. L'altra metà è capire come convivere con il Dev Mode nel lavoro quotidiano.

Ci sono due grandi tipi di modifiche: modifiche alla UI (widget) e modifiche alla logica/agli strumenti MCP.

Se cambi solo la UI, ad esempio in app/page.tsx modifichi un titolo o gli stili, per Next.js è normale frontend. Il dev server ricarica il modulo e nel browser vedi l'hot reload. In ChatGPT la tua UI è aperta in un iframe, ma il comportamento è simile: alla prossima invocazione dello strumento che renderizza quel widget, ChatGPT caricherà l'HTML aggiornato. A volte l'HMR arriva direttamente all'iframe, a volte basta invocare di nuovo lo strumento in chat. CACHE

Prova, per fissare, a cambiare un po' il widget. Supponiamo che in app/page.tsx tu abbia qualcosa del tipo:

export default function GiftGeniusWidget() {
  return (
    <main style={{ padding: 16 }}>
      <h1>GiftGenius</h1>
      <p>Qui verrà effettuata la selezione dei regali.</p>
    </main>
  );
}

Modifica titolo e testo:

export default function GiftGeniusWidget() {
  return (
    <main style={{ padding: 16 }}>
      <h1>GiftGenius (dev)</h1>
      <p>Questa versione vive in Dev Mode. Non per regali di produzione.</p>
    </main>
  );
}

Salva il file, torna nella chat con GiftGenius collegato e invoca di nuovo l'app (ad esempio con la stessa richiesta sul regalo). Dovresti vedere il titolo aggiornato dentro il widget — è un buon segno che la catena Next.js → tunnel → ChatGPT funziona.

Se invece cambi la parte MCP — aggiungi un nuovo strumento, cambi lo schema di inputSchema, modifichi i nomi dei tools — entra in gioco la cache di ChatGPT. Al primo collegamento in Dev Mode, ChatGPT memorizza l'elenco degli strumenti e non sempre recepisce automaticamente le modifiche. In tal caso devi tornare nella sezione Apps & Connectors, selezionare il tuo GiftGenius (dev) e premere qualcosa come Refresh schema / Refresh. Dopo di ciò ChatGPT interrogherà di nuovo il tuo /mcp e aggiornerà l'elenco dei tools.

Sembra un dettaglio, ma senza questo è facile «beccare» la situazione: hai già corretto il codice dello strumento, ma ChatGPT continua a non vedere i nuovi parametri.

8. Mini pratica: primo scenario completo di GiftGenius in Dev Mode

Mettiamo tutto insieme in uno scenario pratico. Qui darò per scontato che tu abbia un qualsiasi URL HTTPS funzionante per /mcp (tramite tunnel o deploy). Se al momento non ce l'hai — leggi semplicemente i passaggi, nella prossima lezione li ripeterai con un URL reale.

1. Assicurati che npm run dev sia avviato e che nei log non ci siano errori. È particolarmente piacevole vedere qualcosa tipo «MCP server running at http://localhost:3000/mcp» nel terminale, se il template lo logga.
2. Apri ChatGPT, attiva il Developer Mode tramite Settings → Apps & Connectors → Advanced settings.
3. Crea un nuovo connettore GiftGenius (dev) con una breve descrizione («Helper for choosing gifts») e un URL del tipo https://<tuo-dominio>/mcp.
4. Verifica che ChatGPT sia riuscito a collegarsi: nell'elenco delle app vedrai il nuovo elemento. Se il collegamento non c'è — guarda i log del dev server e del tunnel, è utile di per sé.
5. Apri una nuova chat, clicca «+», seleziona il tuo GiftGenius (dev), poi formula la richiesta: «Scegli un regalo per uno sviluppatore che ama lo spazio e il caffè, budget 40$».
6. Guarda cosa fa il tuo template attuale: nella forma base può mostrare una semplice card/widget. Non è ancora una «scelta intelligente dei regali», ma il fatto che qualcosa appaia in chat dal tuo codice è già un enorme passo avanti.

Come esercizio aggiuntivo puoi creare uno strumento di test separato nel server MCP solo per verificare il Dev Mode. Esempio (non è necessario implementarlo subito, guarda solo l'idea):

// all'interno di app/mcp/route.ts, accanto ad altri tools
server.registerTool(
  "ping_dev",
  {
    title: "Ping GiftGenius dev",
    description: "Verifica che il server Dev sia attivo.",
    inputSchema: { type: "object", properties: {} },
  },
  async () => ({
    content: [{ type: "text", text: "GiftGenius dev is alive ✅" }],
    structuredContent: {},
  })
);

Analizzeremo in dettaglio server.registerTool nel modulo sugli strumenti; per ora ricordiamo: tramite MCP descrivi «che cosa sa fare la tua App», e il Dev Mode è il modo per dare a ChatGPT l'URL a cui queste capacità sono dichiarate.

9. Dove guardare gli errori e come distinguere «si è rotto da me» da «si è rotto in ChatGPT»

Nessuno ama cercare bug per mezz'ora «nella metà sbagliata del sistema», quindi conviene formarsi subito l'abitudine di guardare nel posto giusto.

Se l'errore compare durante la creazione del connettore. Se durante la creazione del connettore ChatGPT scrive che non può collegare l'App, per prima cosa guarda i log del tuo dev server e del tunnel. Se nel terminale dove gira npm run dev non ci sono affatto richieste in ingresso a /mcp — il problema è sul percorso ChatGPT → tunnel. Se le richieste ci sono, ma il server risponde 500 o va in errore in console — il problema è nel tuo codice MCP.

Se il connettore è già creato ma si rompe in chat. Quando il connettore è già creato e in chat compare periodicamente il banner «App unavailable / App broken», quasi sempre significa che:

• il dev server è crashato (Next.js ha smesso di ascoltare la porta 3000);
• il tunnel è spento o l'URL è cambiato;
• l'endpoint MCP restituisce un errore, timeout o risponde molto lentamente.

A parte l'UI/widget. Per problemi con la UI (il widget non si renderizza, schermo vuoto, stili strani) guarda anche i DevTools del browser. Il widget viene caricato in un iframe, e nella console di quell'iframe vedi gli errori JavaScript/React — esattamente come in una normale web app.

Con l'esperienza comincerai a distinguere «sa di tunnel» da «sa di Next.js» letteralmente dall'aspetto dell'errore, ma per ora basta ricordare: hai tre potenziali punti di guasto — il tuo codice, il tunnel e ChatGPT — e la probabilità che il problema sia in ChatGPT è di solito la più bassa.

Insight

Se stai leggendo questo testo e non hai un tunnel a pagamento, puoi comprarlo subito. Lo farai comunque nei prossimi giorni. Quindi risparmia semplicemente i nervi.

10. Errori tipici nel lavoro con il Dev Mode

Errore n. 1: hai dimenticato di attivare il Developer Mode e cerchi il pulsante Create per mezz'ora.
A volte gli sviluppatori aprono subito ChatGPT, vanno in Apps & Connectors e non vedono nulla di interessante. Senza il Developer Mode attivo, il pulsante per creare un connettore potrebbe non esserci affatto. Inizia sempre verificando che il Dev Mode sia abilitato in Advanced settings, soprattutto su account nuovi o in un altro browser.

Errore n. 2: hai incollato un URL senza /mcp o non un vero MCP endpoint.
Classico: nel campo URL si incolla https://myapp-dev.ngrok.app senza il percorso /mcp, oppure addirittura l'URL della landing/di un altro servizio. ChatGPT bussa educatamente lì con il protocollo MCP, non trova l'interfaccia attesa e risponde con un errore di connessione. Il template Next.js starter lo dice chiaramente: bisogna collegarsi a un URL che punti a /mcp — ed è proprio questo che va indicato nel Dev Mode.

Errore n. 3: tentare di usare http://localhost:3000/mcp direttamente.
Istintivamente viene voglia di incollare nel campo URL proprio http://localhost:3000/mcp, quello che vedi nei log del dev server. Ma ChatGPT gira nel cloud, non sul tuo portatile, e non ha accesso al tuo localhost. Inoltre ChatGPT richiede HTTPS. Quindi senza tunnel o deploy remoto non funzionerà. Non è un bug di ChatGPT, è normale isolamento di rete.

Errore n. 4: dimenticare il Refresh dopo aver cambiato lo schema MCP.
Dopo un handshake riuscito, ChatGPT mette in cache l'elenco degli strumenti e dei metadati per non interrogare il server ogni volta. Se hai aggiunto un nuovo tool o cambiato il suo inputSchema, e ChatGPT continua a comportarsi come prima, quasi certamente serve un Refresh del connettore nella sezione Apps & Connectors. Senza questo, il modello semplicemente non sa che gli strumenti sono cambiati.

Errore n. 5: cercare di fare debug del Dev Mode quando il dev server non è avviato.
Sembra ovvio, ma succede spesso: uno studente configura da remoto Dev Mode e tunnel, mentre nel suo terminale npm run dev non gira più da tempo o il progetto non si compila per un errore di sintassi. Finché il dev server locale è giù, è inutile inseguire errori del Dev Mode. Assicurati sempre prima che http://localhost:3000 funzioni nel tuo browser, e solo dopo collega ChatGPT.

Errore n. 6: aspettarsi che il Dev Mode sia «un altro modello che capisce tutto».
A volte sembra che, avendo attivato il Dev Mode, il modello «sappia» tutto sulla nostra app. In realtà il Dev Mode non cambia il modello, gli dà soltanto accesso al tuo server MCP e ai suoi strumenti. Se gli strumenti sono descritti in modo vago, la descrizione dell'App è poco chiara o la logica del server è strana, il modello si confonderà come qualsiasi sviluppatore che apre un'API documentata male. Buoni metadati e strumenti — tema dei prossimi moduli, ma è bene ricordarlo già ora.

Errore n. 7: usare il Dev Mode come produzione.
La tentazione c'è: «Vabbè, da noi tutto funziona bene in Dev Mode, diamo il link agli utenti così collegano l'App a questo URL». Il problema è che il Dev Mode non è pensato per l'uso di massa: i tunnel sono instabili, le configurazioni possono rompersi e lo stesso ChatGPT può cambiare il comportamento del Dev Mode senza retrocompatibilità. Per gli utenti reali ci sono lo Store e il deploy di produzione. Il Dev Mode — esclusivamente il tuo laboratorio.