Collega un client MCP a Fotoluce

Fotoluce espone il catalogo fotografico tramite un server MCP remoto. La connessione usa Streamable HTTP all'indirizzo canonico:

https://www.fotoluce.it/mcp

MCP abilitato nella configurazione di questo ambiente. Verifica il collegamento dal tuo client.

Versioni e strumenti

Il server configurato supporta queste versioni sullo stesso endpoint; l'effettiva disponibilità va verificata separatamente:

2026-07-28: client MCP moderni, con discovery MCP e versione esplicita in ogni richiesta.
2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05 e 2024-10-07: client legacy con handshake di inizializzazione.

Senza account collegato sono disponibili ricerca e schede dei prodotti pubblicati e informazioni sui negozi. Le funzioni account richiedono il tuo consenso OAuth: identità, carrello, passaggio al checkout e lettura degli ordini. Il collegamento account OAuth è abilitato nella configurazione di questo ambiente.

Esempio di configurazione JavaScript

Questo esempio usa il client MCP JavaScript @modelcontextprotocol/client versione 2.3.1 e fissa esplicitamente il protocollo moderno. Per client diversi, usa la loro configurazione MCP documentata: formato e nomi dei campi possono variare.

import { Client } from "@modelcontextprotocol/client";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/client";

const client = new Client(
  { name: "fotoluce-example", version: "1.0.0" },
  { versionNegotiation: { mode: { pin: "2026-07-28" } } }
);
const transport = new StreamableHTTPClientTransport(
  new URL("https://www.fotoluce.it/mcp")
);
await client.connect(transport);
const tools = await client.listTools();

Esempio di configurazione JSON per Inspector

Per MCP Inspector CLI 2.9.0, salva questo esempio come file di sessione JSON. In Inspector, type: "http" indica Streamable HTTP e protocolEra: "modern" sceglie il profilo moderno; non fissa una data di protocollo. Questo campo è specifico di Inspector. Altri client possono usare chiavi diverse: imposta lo stesso URL e il trasporto Streamable HTTP nella loro configurazione.

{
  "mcpServers": {
    "fotoluce": {
      "type": "http",
      "url": "https://www.fotoluce.it/mcp",
      "protocolEra": "modern"
    }
  }
}

Un client legacy JavaScript può invece usare @modelcontextprotocol/sdk versione 1.32.1 con StreamableHTTPClientTransport e handshake standard; il server non converte automaticamente una richiesta moderna in legacy o viceversa.

Collegamento facoltativo dell'account

L'issuer OAuth è https://www.fotoluce.it. I metadati sono pubblicati in discovery authorization-server e in discovery della risorsa (anche sul percorso specifico /.well-known/oauth-protected-resource/mcp). La registrazione client dinamica resta disponibile. I client pubblici usano authorization code con PKCE S256; non inserire una password Fotoluce o un client secret nella configurazione.

Prima di concedere l'accesso, controlla nome, dominio dei metadati quando presente, indirizzo completo di ritorno e autorizzazioni nella schermata Fotoluce. Il nome è dichiarato dal client e non ne prova l'identità. Puoi annullare il consenso; la revoca OAuth è disponibile all'endpoint https://www.fotoluce.it/oauth/revoke secondo il supporto del client.

account:read — identità dell'account collegato.
cart:read — contenuto del carrello Fotoluce.
cart:write — modifiche al carrello condiviso.
checkout:create — creazione di un link temporaneo al checkout.
orders:read — ordini e stato di spedizione dell'account.

Callback native e redirect

Un'applicazione nativa può usare callback HTTP loopback su 127.0.0.1 o [::1]. Quando il profilo è ammesso, il client può scegliere una porta effimera; percorso e query devono restare identici alla registrazione. Questa eccezione non ammette altri indirizzi HTTP.

Il dominio dei metadati client (quando è usata un'identità CIMD) identifica la configurazione del client; non è il callback OAuth. Il callback è un URI separato registrato dal client. Un redirect tra origini è consentito solo se la coppia esatta URL dei metadati e URI callback è configurata qui sotto.

Le identità client da URL CIMD sono disabilitate in questo ambiente. Il callback loopback è disabilitato; un flag loopback attivo da solo non abilita CIMD. CIMD non è necessario per la registrazione OAuth dinamica.

Le coppie di redirect CIMD non sono attive perché CIMD è disabilitato.

Se il ritorno non funziona, controlla che il client invii esattamente l'URI registrato, che la porta loopback sia in ascolto e che il redirect appartenga al profilo consentito. Per supporto, visita Contatti.

Carrello, checkout e ordini

Il client può preparare un link di checkout monouso e temporaneo. Non piazza né paga l'ordine: apri il sito Fotoluce, ricontrolla articoli e disponibilità, indirizzo o ritiro, sconti, totale e metodo di pagamento, quindi conferma tu nel checkout. Non sono promessi accessi o funzioni speciali di una piattaforma o assistente.

Limiti e tentativi

La configurazione standard di produzione limita la frequenza per IP a 60 richieste al minuto e applica una quota pesata di 60 unità al minuto per client o visitatore. Le richieste concorrenti oltre il limite ricevono HTTP 429 e Retry-After; attendi il valore ricevuto e riprova una sola volta. Timeout e risposte temporanee non autorizzano retry rapidi o ripetuti. Il server limita anche i corpi a 32 KiB, le richieste simultanee a 8 e le risposte MCP a 140.000 byte; usa pagine più piccole per risultati lunghi. Le protezioni possono rifiutare richieste durante un disservizio.