Server MCP (Claude e assistenti IA)

È un ponte sicuro tra i dati della cantina e un client MCP-compatibile. Dopo l’autenticazione, l’assistente può invocare strumenti VinoCellar per conto tuo, nel rispetto dell’abbonamento e delle regole dell’account.

L’URL pubblico esatto è mostrato nell’app VinoCellar, schermata MCP / token (percorso interno /app/mcp), blocco «Indirizzo del server MCP». Copialo così com’è.

Nell’app di produzione pubblica VinoCellar, l’host MCP predefinito è https://mcp.vinocellar.app . Preferisci sempre il valore mostrato nell’app se diverso (build personalizzate o configurazione futura tramite EXPO_PUBLIC_MCP_SERVER_URL).

1. Apri l’app → sezione MCP (o Impostazioni → VinoCellar MCP → gestisci token).
2. Copia l’URL del server dal blocco dedicato.
3. In Claude Desktop (o altro client), aggiungi un server MCP e incolla l’URL secondo la documentazione attuale del client.
4. Al primo collegamento, completa il passaggio OAuth nel browser; incolla il token personale creato nell’app quando richiesto.

Il server MCP VinoCellar segue la specifica MCP con transport Streamable HTTP: il client parla con l’endpoint MCP in HTTPS (non un catalogo REST generico da esplorare a mano).

Alla prima connessione, il client MCP avvia un flusso simile a OAuth. Nel browser incolli il token di accesso personale creato nell’app VinoCellar; il server MCP lo convalida con l’API VinoCellar e rilascia credenziali che il client invia come Bearer token sulle richieste MCP successive.

I token creati dalla schermata MCP sono emessi con gli ambiti mcp:read e mcp:write così che l’assistente possa chiamare gli strumenti registrati da VinoCellar.

Per un controllo rapido di raggiungibilità dell’host (senza sessione MCP completa), il server risponde a GET /ping con il testo semplice pong.

Il token identifica il tuo account presso il server MCP:

1. Nell’app, apri la schermata MCP e crea un token.
2. Assegnagli un’etichetta chiara (es. «MacBook», « Claude Desktop », «Cursor»).
3. Copia subito il valore: viene mostrato una sola volta.
4. Revoca un token dalla stessa schermata se perdi un dispositivo o vuoi disconnettere un client.

Tratta i token come password: chi ha token e URL può accedere alla cantina via MCP fino alla revoca.

Ecco i nomi esatti degli strumenti esposti ai client MCP:

• vinocellar_whoami — verifica il collegamento; la risposta JSON include un oggetto mcp (testo di benvenuto, URL FAQ, suggerimenti sugli strumenti).
• vinocellar_help — restituisce lo stesso JSON di onboarding dell’oggetto mcp di vinocellar_whoami senza richiamare l’API profilo.
• vinocellar_list_wines — inventario ampio; preferisci vinocellar_search_wines per filtrare per nome o dominio.
• vinocellar_search_wines — ricerca testuale sulle tue bottiglie.
• vinocellar_get_caves — elenca le cantine prima di sceglierne una.
• vinocellar_get_cave — layout per caselle; fornisce i log_id per vinocellar_move_bottle.
• vinocellar_move_bottle — sposta una bottiglia in un’altra casella o cantina usando il log_id restituito da vinocellar_get_cave.
• vinocellar_import_wine — aggiunge un vino da wine_data strutturato (forma GeminiWineResponse) e immagini opzionali etichetta davanti/dietro in base64; richiede abbonamento MCP attivo sull’account.

Gli strumenti MCP si limitano alle operazioni di inventario e cantina elencate sopra.

L’assistente Vino in app, l’assistente abbinamenti, il diario degustazioni e altre funzioni IA non sono esposti come strumenti MCP separati — usa l’app mobile o il web per questi casi.

VinoCellar è pensato per chi usa un client MCP compatibile (es. Claude Desktop): copi l’URL del server dall’app e crei un token personale.

Non esiste un’app OAuth partner separata né documentazione OpenAPI «MCP come REST»: il contratto è il protocollo MCP (tools/list e descrizione/schema di ogni strumento come mostrato dal client).

I crediti servono soprattutto alle scansioni etichetta nell’app. L’abbonamento MCP è separato: finché è attivo, le chiamate al server MCP per le operazioni supportate non sono limitate dal saldo crediti scansione allo stesso modo.

Oggi Claude Desktop e i client MCP-compatibili con il transport VinoCellar. Compatibilità ChatGPT e Gemini prevista; consulta le note di rilascio e questa FAQ.