Come collegare NexoPOS a Codex (ChatGPT) con Oxen

Oxen collega un negozio NexoPOS a Codex tramite il Model Context Protocol (MCP). Dopo che la connessione è stata configurata, Codex può utilizzare gli strumenti NexoPOS consentiti dal token Oxen—ad esempio, per trovare prodotti, rivedere gli articoli con scorte basse, riassumere le vendite, cercare ordini e, quando consentito, creare record.

Questa guida copre l’app desktop locale di ChatGPT (Codex), Codex CLI e l’estensione dell’IDE Codex. Questi client condividono la configurazione MCP sullo stesso host Codex. ChatGPT sul web non legge la configurazione locale di Codex di un computer; gli utenti web hanno bisogno di un plugin installato che fornisca la connessione MCP remota.

Che connessione fa

Il percorso dei dati è:

La tua richiesta in Codex → server MCP Oxen → il tuo negozio NexoPOS autorizzato

Oxen fornisce gli strumenti e il contesto di archivio affidabile. Codex decide quale strumento chiamare dalla tua richiesta, Oxen verifica le autorizzazioni del token e NexoPOS restituisce il risultato consentito. Il token determina quale archivio e quali funzionalità sono disponibili, quindi un identificatore di archivio non dovrebbe mai essere aggiunto manualmente a un prompt o a una chiamata di strumento.

L’endpoint Oxen utilizzato in questa guida è:

https://nexocloud.dev/mcp/oxen

Oxen utilizza HTTP Streamable e l’autenticazione tramite token bearer. Durante la verifica di questa guida, l’endpoint ha completato un handshake MCP come Oxen 2.0.0 utilizzando la versione del protocollo 2025-06-18.

Requisiti

Prima di iniziare, assicurati di avere:

Un’installazione funzionante di NexoPOS connessa a Nexo Cloud/Oxen.
Un token di accesso Oxen con le autorizzazioni necessarie per le attività previste.
L’app desktop di ChatGPT con Codex, Codex CLI o l’estensione Codex IDE.
Un progetto locale affidabile se vuoi che la configurazione venga applicata solo a un progetto.

Gli esempi riportati di seguito presuppongono che il progetto contenga un file token.env privato con questa struttura:

TOKEN="replace-with-your-oxen-token"
URL="https://example.com/mcp/oxen"

Non inserire il token reale nella documentazione, nei prompt, negli screenshot, nei commit o in config.toml.

Proteggi prima il token

Aggiungi token.env al file .gitignore del progetto prima di eseguire il commit di qualsiasi file del progetto:

token.env

Se il token è già stato committato o condiviso, rimuovere il file dall’ultimo commit non è sufficiente perché potrebbe rimanere nella cronologia di Git. Revoca il token esposto in NexoPOS/Nexo Cloud, emetti una sostituzione e poi aggiorna token.env.

Usa le autorizzazioni di token più ristrette che coprano il lavoro dell’utente. Un flusso di lavoro di reporting normalmente richiede solo autorizzazioni di lettura; non dovrebbe ricevere automaticamente autorizzazioni per la creazione di clienti, fornitori o prodotti.

Opzione 1: Connetti tramite una variabile d’ambiente

Questa è la configurazione più semplice per Codex CLI o per un IDE avviato dalla stessa sessione di terminale.

1. Carica token.env in PowerShell

Apri PowerShell nella directory del progetto ed esegui:

$oxenSettings = Get-Content -LiteralPath .\token.env | ConvertFrom-StringData
$env:OXEN_TOKEN = $oxenSettings.TOKEN.Trim('"')

Questo imposta OXEN_TOKEN solo per l’attuale processo di PowerShell e per i programmi avviati da esso. La chiusura del terminale lo azzera.

2. Aggiungi la configurazione MCP

Crea o aggiorna .codex/config.toml nel progetto:

[mcp_servers.oxen]
url = "https://example.com/mcp/oxen"
bearer_token_env_var = "OXEN_TOKEN"
enabled = true
required = true
startup_timeout_sec = 20
tool_timeout_sec = 60
default_tools_approval_mode = "writes"

La configurazione MCP definita nell’ambito del progetto viene caricata solo per i progetti attendibili. Per rendere il server disponibile in ogni progetto locale, inserisci la stessa tabella nella configurazione utente in ~/.codex/config.toml invece.

default_tools_approval_mode = "writes" consente agli strumenti in sola lettura di funzionare normalmente, richiedendo l’approvazione prima degli strumenti che non sono contrassegnati come in sola lettura. Mantieni questa impostazione a meno che la policy della tua organizzazione non richieda l’approvazione per ogni chiamata.

3. Avvia Codex dallo stesso terminale

Avvia il client dalla sessione PowerShell che contiene OXEN_TOKEN. Per Codex CLI:

codice

Se un IDE viene avviato tramite un collegamento diverso o da un processo già in esecuzione, potrebbe non ereditare la variabile d’ambiente temporanea. Riavvialo dal terminale preparato oppure usa l’opzione 2.

Opzione 2: Fai leggere a Codex il file token.env tramite un helper di intestazione

Questa opzione è comoda per l’app desktop di ChatGPT perché non dipende dal fatto che l’app erediti una variabile temporanea del terminale. Codex supporta un comando locale http_headers_helper per server HTTP trasmissibili. Il comando deve stampare un oggetto JSON contenente le intestazioni della richiesta.

1. Crea uno script di helper per l’intestazione locale

Crea tools/Get-OxenHeaders.ps1 con il seguente contenuto:

$ErrorActionPreference = 'Stop'

$projectRoot = Split-Path -Parent $PSScriptRoot
$tokenFile = Join-Path $projectRoot 'token.env'

if (-not (Test-Path -LiteralPath $tokenFile)) {
    throw "Oxen token file not found: $tokenFile"
}

$settings = Get-Content -LiteralPath $tokenFile | ConvertFrom-StringData
$token = $settings.TOKEN.Trim('"')

if ([string]::IsNullOrWhiteSpace($token)) {
    throw 'TOKEN is missing from token.env'
}

@{ Authorization = "Bearer $token" } | ConvertTo-Json -Compress

Lo script stampa solo il JSON di intestazione di cui Codex ha bisogno. Non aggiungere output diagnostici perché del testo aggiuntivo renderebbe non valido la risposta dell’helper.

2. Configura il server Oxen

Aggiungi questo a .codex/config.toml, sostituendo il percorso con il percorso assoluto allo script di supporto:

[mcp_servers.oxen]
url = "https://example.com/mcp/oxen"
http_headers_helper = "powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File 'C:\\path\\to\\project\\tools\\Get-OxenHeaders.ps1'"
enabled = true
required = true
startup_timeout_sec = 20
tool_timeout_sec = 60
default_tools_approval_mode = "writes"

Utilizza un solo metodo di autorizzazione. Rimuovi bearer_token_env_var quando usi http_headers_helper; una sorgente esplicita del token bearer ha la precedenza rispetto a un’intestazione Authorization fornita dall’helper.

3. Fiducia e riavvio

Apri il progetto nell’app desktop di ChatGPT e fidati di esso quando richiesto. Poi riavvia Codex per ricaricare la configurazione MCP. Nell’app desktop, il percorso dell’interfaccia equivalente è Impostazioni → Server MCP. Il flusso di configurazione ufficiale consiste nell’aggiungere un server, scegliere Streamable HTTP, fornire il relativo URL, salvare e riavviare.

Verifica la connessione

Nell’app desktop di ChatGPT o nell’interfaccia terminale di Codex, inserisci:

/mcp

Conferma che gli oxen sono abilitati e connessi. In un terminale fuori dalla Codex TUI, puoi anche eseguire:

codex mcp list

Segnaposto immagine: uno screenshot del pannello /mcp che mostra Oxen come abilitato e connesso. Ritaglia i server e le informazioni dell’account non pertinenti.

Allora inizia con una richiesta innocua e di sola lettura:

Usa Oxen per mostrarmi cinque prodotti. Restituisci solo il nome di ciascun prodotto, il relativo SKU e le scorte attuali.

Altri utili prompt di verifica includono:

Use Oxen to list the products that are at or below their low-stock threshold.

Use Oxen to summarize paid, unpaid, partially paid, tax, and income totals for this month. Do not create or modify anything.

Use Oxen to search for order NS-1001, then show its line items. Do not make changes.

Il Codex dovrebbe mostrare una chiamata e una risposta dello strumento Oxen, memorizzando i dati restituiti. Se risponde usando solo conoscenze generali senza chiamare Oxen, indica esplicitamente “Usa il server MCP di Oxen” e controlla di nuovo /mcp.

Capacità disponibili degli oxen

L’elenco esatto dipende dalle autorizzazioni del token. Il server verificato ha esposto questi strumenti:

Prodotti e inventario

search_products: trova prodotti per nome, SKU o codice a barre.
get_product : recupera un singolo prodotto tramite il suo identificatore numerico.
get_low_stock_products: trova le scorte con avvisi attivati che sono pari o inferiori alla rispettiva soglia, con informazioni sulla carenza.
search_product_sales: restituisce le vendite aggregate di prodotti limitate classificate per valore.
create_product : crea un singolo prodotto materializzato o smaterializzato utilizzando identificatori di categoria e unità esistenti.
import_products : importa in modo atomico tra 1 e 50 prodotti semplici, con risoluzione di categoria e unità.

Clienti e fornitori

search_customers: cerca per nome, email o telefono.
get_customer : recupera un cliente e i totali dell’account.
create_customer : crea un cliente e indirizzi di fatturazione o di spedizione opzionali.
create_provider: crea un fornitore/fornitore di servizi a partire dai campi di contatto consentiti.

Ordini, finanza e reportistica

search_orders: cerca per codice ordine, intervallo di date o stato del pagamento.
get_order: recupera un ordine e le relative righe.
search_wallet_history: recupera le voci dell’estratto conto del portafoglio cliente entro limiti definiti.
get_dashboard_summary: restituisce i totali per pagato, non pagato, parzialmente pagato, imposte e entrate per un intervallo di date.
generate_report: crea un report PDF/anteprima HTML con branding oppure un’esportazione CSV dalle sezioni del report vincolato.

Oxen ha anche esposto risorse di riferimento sicure per la configurazione attuale del negozio, i tipi di pagamento, le categorie di prodotto e i gruppi fiscali. Codex può utilizzare tali risorse per scegliere identificatori validi e formattare i risultati per il negozio connesso.

Segnaposto immagine: una conversazione nel Codex che mostra una richiesta di disponibilità ridotta in sola lettura, la chiamata dello strumento Oxen e una breve tabella dei risultati con parti oscurate.

Leggi azioni vs azioni di scrittura

Les recherches, les recherches approfondies, les résumés et les lectures de ressources de référence ne modifient pas NexoPOS. Les outils de création et d’import modifient NexoPOS.

Prima di approvare una chiamata di scrittura, rivedi ogni campo mostrato da Codex. In particolare:

Controlla nomi, prezzi, codici a barre, SKU, ID categoria, gruppi unità e impostazioni fiscali.
Utilizza un identificativo univoco di idempotency_key per ogni scrittura prevista. Se una richiesta deve essere riprovata, riutilizza la stessa chiave affinché un retry di rete non crei un duplicato.
Confermare i recapiti del cliente e del fornitore prima di trasmetterli.
Testa i permessi di scrittura con un record temporaneo chiaramente denominato solo quando la policy del tuo store lo consente e rimuovilo successivamente da NexoPOS, se appropriato.
Ricorda che import_products è atomico: l’intero batch viene ripristinato quando una qualsiasi riga non riesce.

Un prompt sicuro in due passaggi è:

Prepare the Oxen arguments for a new product named “House Blend 250 g” at 12.50. First read the available product categories and units. Show me the proposed values, but do not call create_product until I approve them.

Segnaposto immagine: uno screenshot di Codex che mostra un’azione create_product proposta e in attesa di approvazione, con identificatori specifici del negozio oscurati.

Richieste pratiche dopo la configurazione

Una volta che i controlli di sola lettura funzionano, Codex può gestire domande a più passaggi come:

Use Oxen to find low-stock products, rank them by shortage, and explain which five need attention first. Do not modify inventory.

Use Oxen to compare this month's dashboard totals with last month's. Show the absolute and percentage changes and flag any unpaid balance.

Use Oxen to find the top 10 products by sales value, then generate a branded PDF report with KPI cards and a bar chart. Show me the planned report sections before creating the file.

Read this CSV, validate each product against the available NexoPOS categories and units, report all problems, and wait for my approval before calling import_products.

Risoluzione dei problemi

Gli ossi non compaiono in /mcp

Conferma che il file di configurazione si chiama esattamente .codex/config.toml per una configurazione a livello di progetto oppure config.toml in ~/.codex per una configurazione a livello utente.
Assicurati che il progetto sia attendibile.
Riavvia l’app desktop di ChatGPT o l’estensione dell’IDE dopo aver modificato le impostazioni MCP.
Esegui “codex mcp list” e “codex mcp --help” da un terminale.
Convalida la sintassi TOML, soprattutto le barre rovesciate di Windows e le virgolette in http_headers_helper.

Il server restituisce 401 Unauthorized

Verifica che TOKEN esista in token.env e che non contenga spazi accidentali.
Se si utilizza bearer_token_env_var, verificare che OXEN_TOKEN sia definita nell’ambiente da cui è stato avviato Codex.
Se usi l’helper, eseguilo direttamente e verifica che produca un singolo oggetto JSON compatto. Non visualizzare né condividere l’output perché contiene il token bearer.
Riemetti il token se è stato revocato, scaduto o esposto.

Il server restituisce 403 Forbidden

Il token viene riconosciuto, ma non dispone dell’autorizzazione per la funzionalità richiesta oppure la policy del negozio lo blocca. Chiedi all’amministratore di NexoPOS di concedere solo l’ambito necessario. Non aggirare il limite delle autorizzazioni inserendo identificatori del negozio o credenziali nel prompt.

Les outils de lecture fonctionnent, mais les outils de création sont manquants

Di solito si tratta di un problema di autorizzazione, non di un errore di connessione. Oxen espone strumenti con ambito di autorizzazione, quindi un token in sola lettura potrebbe intenzionalmente omettere create_product, create_customer, create_provider o import_products.

L’app desktop si connette, ma ChatGPT web no

Questo è previsto. I client Local Codex condividono la configurazione MCP dell’host, ma ChatGPT web non legge il file locale .codex/config.toml. ChatGPT web richiede un plugin installato che includa o si colleghi al server MCP remoto e potrebbe anche essere controllato dagli amministratori dell’area di lavoro.

La connessione va in timeout

Conferma che https://nexocloud.dev/mcp/oxen è raggiungibile dal computer.
Verifica le regole del proxy, del firewall e del DNS.
Aumenta startup_timeout_sec se la connessione è lenta.
Mantieni tool_timeout_sec sufficientemente alto per la generazione del report, che potrebbe richiedere più tempo rispetto a una semplice ricerca.

Checklist di sicurezza

Mantieni token.env fuori da Git e dai backup destinati alla condivisione.
Non incollare mai un token in un prompt di Codex.
Non inserire mai il token direttamente in config.toml.
Usa HTTPS e l’esatto endpoint Oxen.
Concedi le autorizzazioni dello strumento più ristrette possibile.
Mantieni abilitati gli approvatori dello strumento di scrittura.
Rivedi le bozze proposte prima di approvarle.
Revoca e sostituisci qualsiasi token che potrebbe essere stato esposto.
Usa token separati per gli archivi di produzione e di test.
Rimuovi o disabilita la voce MCP quando non è più necessario l’accesso.

Disconnetti Oxen

Per disabilitare il server senza eliminarne le impostazioni:

[mcp_servers.oxen]
enabled = false

In alternativa, rimuovi la sezione [mcp_servers.oxen] e riavvia Codex. Pulisci la variabile di shell corrente con:

Remove-Item Env:OXEN_TOKEN

Se il computer o il repository sta cambiando proprietario, revoca anche il token.