Server MCP di Insights

Collega ChatGPT, Claude, Copilot o Gemini al tuo tenant Fooodo Insights tramite il server remoto Model Context Protocol.

Auto-translated · pending native review. The English version is canonical.

Fooodo Insights include un server remoto Model Context Protocol per tenant. Espone le analisi operative della tua organizzazione e un insieme limitato di azioni di scrittura delimitate a qualsiasi client AI che supporta MCP — senza chiavi API, integrazioni personalizzate o copia-incolla.

Chi può utilizzarlo? Qualsiasi cliente Fooodo Insights con accesso admin, analyst o viewer a un tenant che ha il flag funzionalità mcp_enabled attivato. Il flag è disattivato per impostazione predefinita per ogni organizzazione; contatta support@fooodo.com per richiedere l'abilitazione e ricevere l'URL MCP del tuo tenant.

Due server MCP, una sola famiglia di prodotti. Questa pagina riguarda il server MCP di Insights, che espone le analisi operative per tenant tramite OAuth 2.1. Un server MCP del manuale di marketing separato è in esecuzione su /api/mcp su fooodo.com ed è pubblico — gli agenti lo utilizzano per conoscere Fooodo e inviare richieste di contatto commerciale. Le due superfici sono deliberatamente separate: contenuto del manuale vs. dati dei clienti.

Perché MCP

MCP è lo standard aperto che i client AI utilizzano per comunicare con dati e strumenti remoti — l'equivalente per gli agenti di OAuth + REST. Un singolo server MCP può essere aggiunto una volta e riutilizzato da ChatGPT, Claude, Copilot, Gemini, Cursor, Windsurf, Zed e dal crescente elenco di client conformi.

Per i clienti di Fooodo Insights questo significa:

Nessun vendor lock-in. Il tuo analista può porre la stessa domanda da ChatGPT oggi e da Gemini domani senza riconfigurare nulla.
Azioni delimitate e verificate. Gli strumenti di scrittura (ad es. attiva importazione dati, conferma avviso) richiedono lo scope insights:write e un ruolo admin o analyst. Ogni scrittura viene registrata nel log di audit con source: "mcp".
Isolamento del tenant. Gli strumenti sono limitati all'organizzazione dell'utente a livello di database; l'accesso cross-tenant è impossibile.

Connetti dal tuo AI

Il server MCP di Insights supporta OAuth 2.1 con Dynamic Client Registration, quindi ogni client qui sotto utilizza lo stesso flusso con un clic: incolla l'URL del tuo tenant, fai clic su Connetti, accedi con il tuo account Fooodo Insights, approva gli scope — fatto.

I frammenti di codice qui sotto utilizzano <INSIGHTS_MCP_URL> come segnaposto. Sostituiscilo con l'URL che il supporto Fooodo ti invia dopo aver abilitato MCP per il tuo tenant.

ChatGPT (Plus / Pro / Enterprise)

Apri Impostazioni → Connettori → Aggiungi connettore personalizzato (la Modalità Sviluppatore deve essere abilitata).
URL server: <INSIGHTS_MCP_URL>.
Approva la pagina di consenso quando richiesto.

Claude.ai (Pro e superiori)

Apri Impostazioni → Connettori → Aggiungi connettore personalizzato.
Nome: Fooodo Insights. URL server: <INSIGHTS_MCP_URL>.
Approva la pagina di consenso.

GitHub Copilot (VS Code 1.101+, JetBrains, Visual Studio)

Aggiungi al file .vscode/mcp.json del tuo workspace:

{
  "servers": {
    "fooodo-insights": {
      "type": "http",
      "url": "<INSIGHTS_MCP_URL>"
    }
  }
}

Se utilizzi Copilot Business/Enterprise, il tuo amministratore deve prima abilitare il criterio Server MCP in Copilot.

Gemini CLI

Aggiungi alla configurazione di Gemini CLI:

{
  "mcpServers": {
    "fooodo-insights": {
      "url": "<INSIGHTS_MCP_URL>",
      "oauth": true
    }
  }
}

Gemini Enterprise

Nella console Google Cloud, registra il server come archivio dati MCP personalizzato:

Campo	Valore
URL server	`<INSIGHTS_MCP_URL>`
Autenticazione	OAuth 2.0 (Dynamic Client Registration)
Scope richiesti	`insights:read`, `insights:write`

Cosa può fare l'agente

Il server espone strumenti in tre livelli. I client dovrebbero scegliere il livello più basso che risponde alla domanda — è più economico, più veloce e deterministico.

Livello 1 — Strumenti dati (veloci, deterministici, sola lettura)

Strumento	Restituisce
`get_period_summary`	Metriche aggregate per un intervallo di date — vendite, COGS, EBIT, margine lordo, campagne principali
`get_weekly_sales_data`	Vendite settimana per settimana con campagne attive e dati sui costi
`get_channel_stats`	Metriche di performance per canale di marketing — campagne e canali di acquisizione, non la suddivisione dine-in/consegna (per quella, usa `get_channel_breakdown`)
`get_daily_performance`	Vendite giorno per giorno per canale e ristorante
`get_product_performance`	Classifica prodotti/voci di menu per vendite e quantità, con suddivisione per categoria
`get_cfo_pnl_data`	Dettaglio P&L — ricavi, COGS, lavoro, OpEx, EBIT — per la vista dashboard CFO
`get_restaurant_performance`	Dettaglio vendite per ristorante/sede per un intervallo di date, con la quota di ciascuna sede sul totale della catena
`get_channel_breakdown`	Suddivisione del canale vendite (dine-in / consegna / Wolt / Bolt / asporto) con quota in € e % — la controparte lato vendite; i canali di marketing si trovano in `get_channel_stats`
`get_check_metrics`	Scontrino medio (€, al netto dell'IVA), piatti per scontrino e conteggio scontrini per un intervallo di date — con suddivisioni per tipo di ordine e per ristorante
`get_table_times`	Tempo medio di chiusura tavolo (minuti) e conteggio ordini — un indicatore della velocità del servizio — con suddivisioni opzionali per tipo di ordine e ristorante
`get_waiter_times`	Tempi medi di chiusura tavolo per cameriere per un singolo ristorante (richiesto `restaurant_id`)
`get_guest_feedback`	Soddisfazione degli ospiti — punteggi del sondaggio NPS (cibo / servizio / ristorante) più le ultime valutazioni Google per ristorante
`get_cash_position`	Saldo di cassa attuale, tasso di consumo settimanale, runway e saldi per entità
`get_goals_vs_actuals`	Obiettivi KPI (scontrino medio, piatti per scontrino) e budget giornaliero vendite vs. effettivo, con raggiungimento del conteggio ordini
`get_monthly_sales_plan`	Piano vendite mensile prospettico — budget ricavi e conteggio ordini per canale e ristorante, inclusi i mesi futuri
`get_marketing_spend`	Spesa di marketing mensile (dal P&L) e calendario campagne per l'intervallo
`list_restaurants`	Directory ristoranti (id, codice, nome, città) — risolve un nome o codice nel `restaurant_id` su cui filtrano gli altri strumenti dati
`get_menu_sales`	Dettaglio vendite piatti anno su anno per ristorante o città (solo pranzo o generale), con filtro canale opzionale

Livello 2 — Agenti specialisti (analisi LLM a dominio singolo)

Strumento	Restituisce
`consult_financial_analyst`	Analisi del "perché" esclusivamente finanziaria basata sui dati del periodo
`consult_marketing_strategist`	Analisi causale dell'incremento e dell'attribuzione delle campagne esclusivamente di marketing
`consult_market_research`	Contesto di mercato — stagionalità, festività, tendenze del comportamento dei consumatori

Le risposte degli specialisti sono calcolate, non improvvisate: l'aritmetica multi-step viene eseguita da un calcolatore deterministico lato server, non dal calcolo mentale dell'LLM, e ogni cifra porta un'etichetta di confidenza e una citazione della fonte. Per le domande sull'impatto sui profitti, recupera prima il baseline P&L con get_cfo_pnl_data e passa le cifre rilevanti (EBIT baseline, costi) a consult_financial_analyst — gli strumenti propri dello specialista coprono solo i dati di vendita.

Livello 3 — Orchestratore (sintesi cross-domain)

Strumento	Restituisce
`ask_orchestrator`	Instrada una domanda cross-domain a tutti gli agenti specialisti e sintetizza un'unica risposta

Ricerca e recupero (ChatGPT Deep Research, client generici)

Strumento	Restituisce
`search`	Elenco di insight e cronologia delle azioni degli agenti corrispondenti a una query — `{id, title, url, snippet}`
`fetch`	Contenuto completo di un documento tramite id da `search` — `{id, title, text, url, metadata}`

Strumenti di scrittura (richiedono `insights:write` + ruolo `admin`/`analyst`)

Strumento	Esegue
`trigger_data_import`	Attiva immediatamente un recupero file pianificato configurato (asincrono — restituisce un `job_id`)
`acknowledge_alert`	Contrassegna un avviso come confermato
`resolve_alert`	Risolve un avviso
`generate_report`	Genera un report aziendale — riepilogo esecutivo, performance delle campagne, analisi dei canali — per un intervallo di date; asincrono (restituisce un `job_id`), opzionalmente inviato via email
`regenerate_insights`	Riesegue il generatore di insight per l'organizzazione (asincrono)
`get_job_status`	Interroga lo stato di un job asincrono

Prompt

weekly_business_review, margin_diagnosis — prompt con comando slash per ChatGPT Apps e altri client che supportano i prompt.

Sicurezza e limiti

OAuth 2.1 + PKCE, client pubblici, token di aggiornamento a rotazione. I token di accesso sono JWT HS256 validi per un'ora. I token di aggiornamento sono validi per 60 giorni, archiviati come hash SHA-256, a uso singolo alla rotazione.
Controllo per organizzazione tramite il flag funzionalità mcp_enabled — disattivato per impostazione predefinita per ogni organizzazione. L'abilitazione avviene tramite ticket di supporto, non tramite un'opzione self-service, in modo che i clienti possano gestire il rollout in fasi.
Limiti di frequenza per livello per utente. Strumenti dati 60/min; specialisti e orchestratore 10 ogni 5 min; strumenti di scrittura 5 ogni 5 min.
Revoca. Gli utenti possono revocare qualsiasi client in qualsiasi momento dalle impostazioni del proprio account (/account/connected-apps sul lato Insights). Gli amministratori possono revocare a livello di organizzazione.
Audit trail. Ogni chiamata a uno strumento di scrittura viene registrata nel log di audit con source: "mcp", incluso il nome del client, l'utente e il payload di input.
Isolamento del tenant a livello di database. Ogni query è limitata all'organizzazione dell'utente prima di lasciare l'applicazione; il server non può restituire dati cross-tenant.

Per gli sviluppatori di agenti

URL di discovery: <INSIGHTS_MCP_URL>/.well-known/oauth-authorization-server (e con suffisso /mcp, secondo RFC 8414 §3.1).
Metadati della risorsa protetta: <INSIGHTS_MCP_URL>/.well-known/oauth-protected-resource/mcp (secondo RFC 9728).
Dynamic Client Registration: POST <INSIGHTS_MCP_URL>/register — registrazione aperta, ma ogni autorizzazione richiede comunque il consenso interattivo.
Scope: insights:read (predefinito) e insights:write (per gli strumenti di scrittura).
Trasporto: HTTP streamable, versione del protocollo MCP 2025-06-18.

Standard seguiti: MCP 2025-06-18, RFC 6749 (OAuth 2.0), RFC 7636 (PKCE), RFC 7591 (Dynamic Client Registration), RFC 8414 (Authorization Server Metadata), RFC 9728 (Protected Resource Metadata).

Server MCP di Insights

In questa pagina