Server MCP

Wink espone due server MCP autenticati. Entrambi utilizzano login OAuth2 interattivo (flusso di autorizzazione con codice PKCE) — il tuo agente AI apre una scheda del browser per effettuare l’accesso con il tuo account Wink. Nessun segreto client da gestire.

Server	URL	Cosa fa
Inventory API	https://api.wink.travel/mcp	Inventario, prenotazioni, tariffe, canali di vendita, analisi e tutte le operazioni della piattaforma
Integrations	https://integrations.wink.travel/mcp	Integrazioni con channel manager — sincronizza proprietà, tariffe e disponibilità con OTA

---

Come funziona l’autenticazione

I server MCP di Wink utilizzano il flusso OAuth2 Authorization Code + PKCE e supportano la Dynamic Client Registration (RFC 7591). Ecco cosa succede quando ti connetti per la prima volta:

1. Il client AI scopre il server di autorizzazione dai metadati /.well-known/oauth-protected-resource dell’endpoint MCP.
2. Il client si registra autonomamente tramite Dynamic Client Registration — nessuna configurazione manuale dell’applicazione richiesta.
3. Il client apre una scheda del browser su https://iam.wink.travel. Effettui l’accesso con il tuo account Wink e approvi le autorizzazioni richieste nella schermata di consenso.
4. Wink emette un token di accesso associato al tuo account e collegato alla tua identità.
5. Il client AI allega il token a ogni richiesta MCP. Tutti i risultati degli strumenti sono automaticamente limitati alla tua entità di gestione.
6. I token scadono dopo 3 ore. Il client AI aggiorna silenziosamente il token in background senza richiedere nuovamente l’accesso.

Ogni chiamata agli strumenti viene eseguita sotto la tua identità — le stesse regole ACL che proteggono il portale web si applicano all’agente AI.

---

Collega il tuo client AI

Claude Code

1. Assicurati che Claude Code sia aggiornato:

   npm install -g @anthropic-ai/claude-code

2. Aggiungi il server MCP Inventory di Wink:

   claude mcp add wink-inventory https://api.wink.travel/mcp --transport http

3. Claude Code contatta il server, scopre il server di autorizzazione e apre il browser predefinito.

4. Accedi a Wink e approva la richiesta di autorizzazione nella schermata di consenso.

5. Claude Code conferma la connessione. Digita /mcp per verificare che il server appaia e che i suoi strumenti siano caricati.

Per aggiungere anche il server Integrations:

claude mcp add wink-integrations https://integrations.wink.travel/mcp --transport http

Condividi con il tuo team

Aggiungi --scope project a claude mcp add e Claude Code scriverà l’URL del server in .mcp.json nella radice del repository. Committa quel file — ogni membro del team completerà il proprio accesso browser la prima volta che si connette.

Claude Desktop

1. Modifica il file di configurazione di Claude Desktop:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Aggiungi le voci dei server MCP:

   claude_desktop_config.json

   {
     "mcpServers": {
       "wink-inventory": {
         "type": "http",
         "url": "https://api.wink.travel/mcp"
       },
       "wink-integrations": {
         "type": "http",
         "url": "https://integrations.wink.travel/mcp"
       }
     }
   }

3. Chiudi completamente e riavvia Claude Desktop (usa Esci dal menu — chiudere la finestra non basta).

4. Claude Desktop apre una scheda del browser per ogni nuovo server. Accedi a Wink e approva le autorizzazioni.

5. L’icona della spina nella barra inferiore mostra entrambi i server come connessi.

OpenAI Codex

1. Assicurati che Codex CLI sia installato:

   npm install -g @openai/codex

2. Apri (o crea) il file di configurazione di Codex:

   • macOS / Linux: ~/.codex/config.json
   • Windows: %USERPROFILE%\.codex\config.json

3. Aggiungi le voci dei server MCP di Wink:

   ~/.codex/config.json

   {
     "mcpServers": {
       "wink-inventory": {
         "type": "http",
         "url": "https://api.wink.travel/mcp"
       },
       "wink-integrations": {
         "type": "http",
         "url": "https://integrations.wink.travel/mcp"
       }
     }
   }

4. Avvia Codex. Al primo utilizzo, Codex apre una scheda del browser su https://iam.wink.travel.

5. Accedi a Wink e approva le autorizzazioni richieste.

6. Codex conferma la connessione. Esegui codex e chiedi di elencare gli strumenti disponibili per verificare che i server Wink siano attivi.

Nota

Il supporto MCP di Codex CLI richiede la versione 1.0 o successiva. Esegui codex --version per controllare, e npm install -g @openai/codex per aggiornare.

ChatGPT

Il supporto ai server MCP è disponibile nell’app desktop ChatGPT per abbonati Plus, Pro, Team ed Enterprise.

1. Scarica e installa l’app desktop ChatGPT se non l’hai già fatto.

2. Apri l’app e clicca sull’icona del tuo profilo in alto a destra, poi scegli Impostazioni.

3. Vai su Connettori (o Server MCP a seconda della versione dell’app) e clicca su Aggiungi.

4. Inserisci l’URL del server Inventory di Wink:

   https://api.wink.travel/mcp

   Poi clicca su Connetti.

5. ChatGPT apre una scheda del browser su https://iam.wink.travel. Accedi a Wink e approva le autorizzazioni.

6. Ripeti i passaggi 4–5 per il server Integrations:

   https://integrations.wink.travel/mcp

7. Entrambi i server appaiono nella lista dei Connettori. Avvia una nuova chat — gli strumenti Wink sono disponibili automaticamente.

Limitazione app web

I server MCP sono configurabili solo nell’app desktop. L’interfaccia web di ChatGPT su chatgpt.com non supporta server MCP personalizzati.

Cursor

1. Apri (o crea) il file di configurazione MCP di Cursor:

   • macOS / Linux: ~/.cursor/mcp.json
   • Windows: %USERPROFILE%\.cursor\mcp.json

2. Aggiungi le voci dei server MCP di Wink:

   ~/.cursor/mcp.json

   {
     "mcpServers": {
       "wink-inventory": {
         "type": "http",
         "url": "https://api.wink.travel/mcp"
       },
       "wink-integrations": {
         "type": "http",
         "url": "https://integrations.wink.travel/mcp"
       }
     }
   }

3. Apri Cursor. Vai su Impostazioni → Impostazioni Cursor → MCP e verifica che entrambi i server appaiano con indicatore di stato verde. Se sono rossi, clicca su Aggiorna.

4. Cursor apre una scheda del browser su https://iam.wink.travel. Accedi a Wink e approva le autorizzazioni.

5. Apri una chat (Ctrl+L / Cmd+L) e chiedi a Cursor di elencare gli strumenti Wink disponibili per confermare la connessione.

Configurazione a livello di progetto

Puoi anche posizionare un file mcp.json nella radice del tuo progetto invece che in ~/.cursor/. La configurazione a livello di progetto ha priorità e rende i server disponibili a ogni membro del team che apre il progetto in Cursor.

Windsurf

1. Apri (o crea) il file di configurazione MCP di Windsurf:

   • macOS / Linux: ~/.codeium/windsurf/mcp_config.json
   • Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

2. Aggiungi le voci dei server MCP di Wink:

   ~/.codeium/windsurf/mcp_config.json

   {
     "mcpServers": {
       "wink-inventory": {
         "type": "http",
         "url": "https://api.wink.travel/mcp"
       },
       "wink-integrations": {
         "type": "http",
         "url": "https://integrations.wink.travel/mcp"
       }
     }
   }

3. Riavvia completamente Windsurf (File → Esci, poi riapri).

4. Vai su Impostazioni → Server MCP e verifica che entrambi i server risultino connessi. Windsurf apre una scheda del browser su https://iam.wink.travel al primo utilizzo.

5. Accedi a Wink e approva le autorizzazioni. I server diventano verdi nel pannello delle impostazioni una volta autenticati.

Nota

Il supporto MCP di Windsurf richiede la versione 1.4 o successiva. Controlla tramite Aiuto → Informazioni su Windsurf e aggiorna dal sito di Windsurf se necessario.

Cline (VS Code)

Cline è un’estensione VS Code con un gestore integrato di server MCP. Non è richiesta la modifica manuale del JSON.

1. Installa Cline dal Marketplace di VS Code:

   • Apri VS Code e premi Ctrl+Shift+X / Cmd+Shift+X
   • Cerca Cline e clicca su Installa

2. Clicca sull’icona Cline nella barra attività (sidebar sinistra) per aprire il pannello Cline.

3. Clicca sull’icona Server MCP (icona spina) nella toolbar di Cline, poi scegli Modifica impostazioni MCP.

4. VS Code apre cline_mcp_settings.json. Aggiungi le voci di Wink:

   cline_mcp_settings.json

   {
     "mcpServers": {
       "wink-inventory": {
         "type": "http",
         "url": "https://api.wink.travel/mcp"
       },
       "wink-integrations": {
         "type": "http",
         "url": "https://integrations.wink.travel/mcp"
       }
     }
   }

5. Salva il file. Cline si ricarica automaticamente e apre una scheda del browser su https://iam.wink.travel.

6. Accedi a Wink e approva le autorizzazioni. Entrambi i server appaiono attivi nel pannello Server MCP.

Alternativa: aggiungi tramite URL

Nel pannello Server MCP, clicca su Aggiungi server e incolla direttamente https://api.wink.travel/mcp. Cline popola automaticamente la configurazione e gestisce l’autenticazione senza modificare manualmente il JSON.

---

Ambiti (Scopes)

Quando approvi la schermata di consenso vedrai un dettaglio di cosa l’agente sta richiedendo. I client MCP usano lo stesso vocabolario di permessi del resto della piattaforma — vedi la referenza completa degli scope nella pagina Autenticazione.

Due cose sono specifiche per MCP:

• Gli scope mcp.read, mcp.write e mcp.remove sono richiesti in aggiunta per aprire il trasporto MCP. Un client che possiede uno scope mcp.* è ammesso a /mcp, ma ogni strumento che invoca applica comunque lo scope della sezione dell’endpoint che incapsula (es. booking.read).
• Il client AI richiede solo gli scope di cui ha bisogno. Puoi negare permessi individuali nella schermata di consenso — gli strumenti che richiedono uno scope negato restituiranno un errore se invocati.

---

Risoluzione problemi

La scheda del browser non si apre

Il tuo client AI potrebbe non supportare ancora il flusso PKCE interattivo. Verifica di usare una versione recente:

• Claude Code: npm install -g @anthropic-ai/claude-code
• Codex CLI: npm install -g @openai/codex
• Claude Desktop / ChatGPT desktop: aggiorna tramite l’updater integrato nell’app

401 Unauthorized dopo l’accesso

Il token memorizzato potrebbe essere scaduto. Rimuovi e riaggiungi il server per forzare un nuovo accesso:

# Claude Code
claude mcp remove wink-inventory
claude mcp add wink-inventory https://api.wink.travel/mcp --transport http

Per Claude Desktop e ChatGPT, rimuovi la voce del server dalle impostazioni, riavvia l’app e aggiungilo di nuovo.

403 Forbidden chiamando uno strumento specifico

Lo strumento richiede uno scope che non hai approvato nella schermata di consenso. Riconnetti il server — la schermata di consenso apparirà di nuovo e potrai approvare il permesso mancante.

Il server appare ma le chiamate agli strumenti restituiscono “account non trovato”

Sei connesso a un account Wink senza entità di gestione. Vai su Wink Portal e assicurati che il tuo account sia configurato prima di usare il server MCP.

Il token scade durante la sessione

I token sono validi per 3 ore. Claude Code e Claude Desktop aggiornano i token silenziosamente senza interrompere la sessione. Se vedi errori di autenticazione dopo un lungo periodo di inattività, invia un nuovo messaggio — il client si ri-autenticherà automaticamente.

Codex CLI mostra “MCP server unreachable”

Controlla che il file ~/.codex/config.json sia un JSON valido (senza virgole finali) e che "type": "http" sia impostato. Codex richiede il trasporto HTTP per server remoti; il trasporto stdio è solo per binari locali.

Menu “Connettori” di ChatGPT mancante

Il supporto MCP richiede la versione 1.2024.352 o successiva dell’app desktop ChatGPT e un abbonamento attivo Plus, Pro, Team o Enterprise. Aggiorna l’app e verifica il piano in Impostazioni → Account.

Il server Cursor mostra rosso / “Connessione fallita”

Verifica che ~/.cursor/mcp.json sia un JSON valido e contenga "type": "http". Poi vai su Impostazioni → Impostazioni Cursor → MCP e clicca su Aggiorna. Se l’errore persiste, riavvia completamente Cursor — le modifiche alla configurazione non sempre vengono rilevate senza un riavvio.

I server MCP di Windsurf non compaiono nelle impostazioni

Windsurf richiede un riavvio completo (non solo un reload della finestra) per rilevare le modifiche a mcp_config.json. Usa File → Esci e riapri. Se i server non appaiono ancora, conferma di usare Windsurf 1.4+ tramite Aiuto → Informazioni su Windsurf.

L’opzione “Aggiungi server” in Cline non è visibile

Il gestore server MCP richiede Cline 2.0 o successivo. Apri il pannello Estensioni di VS Code, trova Cline e clicca su Aggiorna se disponibile. Dopo l’aggiornamento, ricarica VS Code (Ctrl+Shift+P → “Developer: Reload Window”).

---

Apri Wink Portal Wink su GitHub