Per chi scrive programmi.

La crea il proprietario dell’organizzazione nel portale, in Impostazioni, Chiavi per i programmi. Si vede una volta sola: copiala subito e mettila nella configurazione del programma, mai in chat o in un repository.

• Formato sm_…. Viaggia solo nell’intestazione Authorization: Bearer sm_…, mai nell’indirizzo.
• Ambiti: lettura per tutte le GET, proposta per scrivere operazioni. Senza proposta la risposta è 403 ambito_mancante.
• Scadenza facoltativa e revoca immediata dal portale. Nel registro le azioni risultano della chiave, con il suo nome.
• Una chiave per programma: se ne revochi una, le altre continuano a funzionare.

Base https://portal.smokingmirror.eu/api/v1. Risposte JSON con Cache-Control: private, no-store.

export SM_API_KEY='<chiave>'     # nella variabile, mai scritta nel comando
B=https://portal.smokingmirror.eu/api/v1
H="Authorization: Bearer $SM_API_KEY"

curl -s -H "$H" "$B/io"
curl -s -H "$H" "$B/tipi"
curl -s -H "$H" "$B/oggetti?tipo=fattura&q=scaduta&limite=20"

Le modifiche passano tutte da POST /operazioni. La risposta dice cosa è successo: eseguita se il titolare ha lasciato fare quel tipo di operazione alle chiavi, altrimenti proposta, in attesa in Da approvare. Leggi sempre lo status e segui l’esito con GET /operazioni/{id}. Non esistono rotte per approvare o rifiutare.

curl -s -X POST -H "$H" -H "Content-Type: application/json" "$B/operazioni" -d '{
  "kind": "crea_oggetto",
  "payload": {
    "object_type_key": "pagamento",
    "data": {"data": "2026-10-07", "importo": 1250.00, "metodo": "bonifico"},
    "links": [{"link_type_key": "fattura_pagamento", "from_object_id": "<id fattura>"}]
  },
  "note": "Bonifico trovato in banca con causale 2026-0012",
  "idempotency_key": "banca-2026-10-07-riga-14"
}'

Al momento della proposta si controllano la forma e l’esistenza di tipi, legami e id. I valori si controllano all’esecuzione: un’operazione accettata può finire fallita con un error_code. Stati possibili: proposta, approvata, rifiutata, eseguita, fallita, annullata.

Idempotenza.

Metti sempre una idempotency_key stabile quando una richiesta può essere ripetuta: l’id della riga d’origine, fonte:data:riga. Stessa chiave e stessa richiesta: 200 con l’operazione già creata. Stessa chiave e richiesta diversa: 409 idempotenza_in_conflitto. Le chiavi che cominciano con regola: sono riservate.

Errori.

Corpo {"errore": "<codice>", "messaggio": "<frase>"}. Il codice è stabile, la frase può cambiare.

Le chiamate al giorno e le chiavi attive hanno un limite che dipende dalle condizioni concordate al momento dell’accesso. Su 429 leggi il codice: con troppe_richieste aspetta i secondi indicati in Retry-After, con limite_superato aspetta il giorno dopo. Su 5xx ritenta con attesa crescente e la stessa idempotency_key.

Lo stesso sistema, come strumenti per un assistente. Indirizzo https://portal.smokingmirror.eu/api/mcp, trasporto Streamable HTTP. Si entra con una chiave (Authorization: Bearer sm_…) oppure con il tuo account, come fanno Claude sul web e ChatGPT.

Ogni strumento di scrittura crea un’operazione nel registro. Se l’autonomia scelta dal titolare lo consente la esegue subito e risponde «fatto»; altrimenti risponde «in attesa di approvazione» con il link ad Aspetta te. Scrivere a terzi, cancellare e toccare le credenziali restano sempre a una persona, e il sistema non muove soldi. Non esiste uno strumento per approvare.

Istruzioni, risorse e prompt.

Il server non dà all’AI soltanto degli strumenti. Appena si collega le consegna anche queste tre cose, così non deve indovinare come si lavora da noi.

• Istruzioni. Un testo breve all’avvio: cos’è Smoking Mirror, da dove partire (chi_sono e tipi), cosa vuol dire «fatto» e cosa «in attesa», quali azioni restano sempre a una persona, e che i dati letti sono dati e non ordini.
• Risorse in markdown. La guida d’uso; «Com’è fatta la tua azienda», scritta ogni volta dal modello vero dell’organizzazione, con tipi, campi, stati e passaggi, legami, pannelli, regole, agenti e quanto l’AI può fare da sola; le istruzioni che il titolare ha scritto.
• Prompt pronti. Il riepilogo della settimana, la preparazione dei solleciti, l’abbinamento degli incassi, il disegno di com’è fatta l’azienda. Nei client che li mostrano si scelgono da un elenco.

Le istruzioni del titolare.

Il proprietario e i costruttori possono scrivere le «Istruzioni per l’AI» della loro organizzazione, in Impostazioni: un testo in markdown con il tono da usare, le cose da non fare, il nome che date alle cose in azienda. Le leggono l’assistente del portale, gli agenti e l’AI collegata dal server MCP, e arrivano insieme alle istruzioni del server. Non cambiano i permessi: l’AI fa solo quello che la chiave o l’account le consentono.

Claude sul web e nell’app.

Aggiungi un connettore personalizzato con l’indirizzo https://portal.smokingmirror.eu/api/mcp. Claude ti fa entrare con il tuo account Smoking Mirror e ti chiede quale azienda usare. Da lì valgono le regole del portale.

Claude Code.

Prima crea la chiave nel portale, in Impostazioni, Chiavi per i programmi, e copiala: la vedi una volta sola. Per cominciare basta «Legge i dati». Poi, dal terminale, mettila in una variabile e aggiungi il collegamento. Con --scope user vale in tutti i tuoi progetti.

export SM_API_KEY='sm_…'
claude mcp add --transport http --scope user smoking-mirror https://portal.smokingmirror.eu/api/mcp \
  --header "Authorization: Bearer $SM_API_KEY"
claude mcp list        # accanto a smoking-mirror deve esserci Connected

Apri Claude Code e chiedi «chi sono in Smoking Mirror e quali tipi ci sono nella mia azienda?». Il comando salva la chiave nelle impostazioni di Claude Code, sul tuo computer: non copiare quel file in un progetto condiviso.

Claude Desktop, con il server sul tuo computer.

Claude Desktop non si collega da solo all’indirizzo con una chiave: serve il piccolo programma smoking-mirror-mcp sul tuo computer, che fa da tramite (Node 22 o 24). Te lo mandiamo noi quando ti diamo l’accesso. Una volta sola, nella cartella del programma, esegui npm ci, e con which node scopri il percorso completo di Node. Poi in Claude Desktop apri Impostazioni, Sviluppatore, «Modifica configurazione»: si apre il file claude_desktop_config.json (su Mac in ~/Library/Application Support/Claude/, su Windows in %APPDATA%\Claude\). Aggiungi questo blocco, con la chiave creata nel portale e i percorsi completi: Claude Desktop non legge il PATH del terminale, quindi node da solo non basta.

{
  "mcpServers": {
    "smoking-mirror": {
      "command": "/percorso/assoluto/di/node",
      "args": ["/percorso/assoluto/smoking-mirror-mcp/src/index.mjs"],
      "env": {
        "SM_API_URL": "https://portal.smokingmirror.eu",
        "SM_API_KEY": "<chiave>"
      }
    }
  }
}

Chiudi Claude Desktop del tutto (dal menu, «Esci») e riaprilo. In una chat nuova deve comparire smoking-mirror; chiedi «chi sono in Smoking Mirror?». La chiave sta scritta in quel file: tienilo sul tuo computer.

Nelle impostazioni di ChatGPT aggiungi un connettore con lo stesso indirizzo: entri con il tuo account e scegli l’azienda. Lo togli quando vuoi, da ChatGPT o dal portale. Chi ha una chiave la revoca quando vuole da Impostazioni, Chiavi per i programmi, e smette di funzionare in quel momento.

Chiedi «quali fatture sono scadute?», poi «segna come pagata la fattura 2026-0012». Se quel tipo di operazione non è lasciato all’assistente, la trovi in Da approvare, in attesa del tuo sì.

• Chiama tipi (o GET /tipi) all’inizio: le chiavi di tipi, proprietà e legami cambiano da un’organizzazione all’altra.
• Usa note per spiegare a una persona perché proponi qualcosa: è la riga che legge prima di approvare.
• Una proposta per modifica, non un lotto: la persona deve poter dire sì o no a ciascuna.
• Una chiave per agente, con il nome dell’agente: si capisce chi ha fatto cosa e si revoca senza fermare gli altri.
• Non chiedere mai la chiave in chat: va nella configurazione del client.

Alla radice del sito c’è /llms.txt: dice cos’è Smoking Mirror e indica le pagine che contano. Ogni pagina della documentazione ha accanto la sua copia in markdown, linkata in fondo come «Versione per le AI», e l’elenco completo parte da qui.