Comment connecter NexoPOS à Codex (ChatGPT) avec Oxen

Oxen connecte une boutique NexoPOS à Codex via le protocole Model Context Protocol (MCP). Une fois la connexion configurée, Codex peut utiliser les outils NexoPOS autorisés par le jeton Oxen — par exemple, pour rechercher des produits, consulter les articles en faible stock, résumer les ventes, rechercher des commandes et, lorsque c’est autorisé, créer des enregistrements.

Ce guide couvre l’application de bureau locale de ChatGPT (Codex), l’interface en ligne de commande Codex (CLI) et l’extension Codex pour l’IDE. Ces clients partagent la configuration MCP sur le même hôte Codex. ChatGPT sur le web ne lit pas la configuration locale Codex d’un ordinateur ; les utilisateurs du web doivent installer un plugin qui fournit la connexion MCP distante.

Quelle est la connexion ?

Le chemin d’accès aux données est :

Votre demande dans Codex → serveur MCP Oxen → votre boutique NexoPOS autorisée

Oxen fournit les outils et le contexte de magasin de confiance. Codex détermine quel outil appeler à partir de votre requête, Oxen vérifie les autorisations du jeton et NexoPOS renvoie le résultat autorisé. Le jeton détermine quel magasin et quelles capacités sont disponibles ; par conséquent, un identifiant de magasin ne doit jamais être ajouté manuellement à une invite (prompt) ou à un appel d’outil.

Le point de terminaison « Oxen » utilisé dans ce guide est :

https://nexocloud.dev/mcp/oxen

Oxen utilise le protocole HTTP Streamable et l’authentification par jeton porteur. Lors de la vérification de ce guide, le point de terminaison a effectué une poignée de main MCP en tant qu’Oxen 2.0.0 en utilisant la version de protocole 2025-06-18.

Exigences

Avant de commencer, assurez-vous d’avoir :

Une installation NexoPOS fonctionnelle connectée à Nexo Cloud/Oxen.
Un jeton d’accès Oxen doté des autorisations nécessaires aux tâches prévues.
L’application de bureau ChatGPT avec Codex, Codex CLI ou l’extension Codex IDE.
Un projet local de confiance si vous souhaitez que la configuration s’applique uniquement à un seul projet.

Les exemples ci-dessous supposent que le projet contient un fichier privé token.env avec cette structure :

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

N’insérez pas le véritable jeton dans la documentation, les invites, les captures d’écran, les commits ou le fichier config.toml.

Protégez d’abord le jeton

Ajoutez token.env au fichier .gitignore du projet avant de valider tout fichier du projet :

token.env

Si le jeton a déjà été validé ou partagé, supprimer le fichier du dernier commit ne suffit pas, car il peut rester dans l’historique Git. Révoquez le jeton exposé dans NexoPOS/Nexo Cloud, émettez un jeton de remplacement, puis mettez à jour token.env.

Utilisez les autorisations de jeton les plus restreintes qui couvrent le travail de l’utilisateur. Un workflow de reporting nécessite normalement uniquement des autorisations de lecture ; il ne doit pas recevoir automatiquement des autorisations de création de clients, de fournisseurs ou de produits.

Option 1 : Se connecter à l’aide d’une variable d’environnement

C’est la configuration la plus simple pour Codex CLI ou pour un IDE lancé depuis la même session de terminal.

1. Charger token.env dans PowerShell

Ouvrez PowerShell dans le répertoire du projet et exécutez :

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

Ceci définit OXEN_TOKEN uniquement pour le processus PowerShell actuel et les programmes lancés à partir de celui-ci. La fermeture du terminal le supprime.

2. Ajouter la configuration MCP

Créer ou mettre à jour le fichier .codex/config.toml dans le projet :

[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 configuration MCP limitée au projet n’est chargée que pour les projets de confiance. Pour rendre le serveur disponible dans chaque projet local, placez la même table dans la configuration utilisateur à ~/.codex/config.toml à la place.

default_tools_approval_mode = "writes" permet aux outils en lecture seule de s’exécuter normalement, tout en demandant une approbation avant les outils qui ne sont pas marqués comme en lecture seule. Conservez ce paramètre sauf si la politique de votre organisation exige que chaque appel soit approuvé.

3. Lancez Codex depuis le même terminal

Lancez le client depuis la session PowerShell qui contient OXEN_TOKEN. Pour Codex CLI :

codex

Si un IDE est lancé à partir d’un autre raccourci ou d’un processus déjà en cours d’exécution, il peut ne pas hériter de la variable d’environnement temporaire. Redémarrez-le depuis le terminal préparé ou utilisez l’option 2.

Option 2 : Laissez Codex lire token.env via un helper d’en-tête

Cette option est pratique pour l’application de bureau ChatGPT, car elle ne dépend pas du fait que l’application hérite d’une variable temporaire de terminal. Codex prend en charge une commande locale http_headers_helper pour les serveurs HTTP diffusables. La commande doit afficher un objet JSON contenant les en-têtes de la requête.

1. Créez un script d’aide pour l’en-tête local

Créer tools/Get-OxenHeaders.ps1 avec le contenu suivant :

$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

Le script n’imprime que le JSON d’en-tête dont Codex a besoin. N’ajoutez aucun message de diagnostic, car du texte supplémentaire rendrait la réponse du helper invalide.

2. Configurer le serveur Oxen

Ajoutez ceci à .codex/config.toml, en remplaçant le chemin par le chemin absolu vers le script d’assistance :

[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"

Utilisez une seule méthode d’autorisation. Supprimez bearer_token_env_var lorsque vous utilisez http_headers_helper ; une source explicite de jeton porteur a priorité sur l’en-tête Authorization fourni par le helper.

3. Confiance et redémarrage

Ouvrez le projet dans l’application de bureau ChatGPT et faites-lui confiance lorsque vous y êtes invité. Ensuite, redémarrez Codex afin qu’il recharge la configuration MCP. Dans l’application de bureau, le chemin d’interface équivalent est Paramètres → Serveurs MCP. Le processus de configuration officiel consiste à ajouter un serveur, choisir Streamable HTTP, fournir son URL, enregistrer, puis redémarrer.

Vérifiez la connexion

Dans l’application de bureau ChatGPT ou l’interface terminal de Codex, saisissez :

/mcp

Confirmez que les bœufs sont activés et connectés. Dans un terminal en dehors de la Codex TUI, vous pouvez également exécuter :

codex mcp list

Espace réservé pour l’image : une capture d’écran du panneau /mcp montrant Oxen comme activé et connecté. Recadrez en supprimant les serveurs et les informations de compte sans rapport.

Ensuite, commencez par une demande inoffensive et en lecture seule :

Utilisez Oxen pour m’afficher cinq produits. Retournez uniquement le nom de chaque produit, son SKU et son stock actuel.

D’autres invites de vérification utiles incluent :

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.

Le Codex doit afficher un appel d’outil Oxen et enregistrer les données renvoyées. S’il répond à partir de connaissances générales sans appeler Oxen, indiquez explicitement « Utilisez le serveur MCP Oxen » et vérifiez à nouveau /mcp.

Capacités disponibles des bœufs

La liste exacte dépend des autorisations du jeton. Le serveur vérifié a exposé ces outils :

Produits et inventaire

search_products : recherchez des produits par nom, SKU ou code-barres.
get_product : récupérer un produit à l’aide de son identifiant numérique.
get_low_stock_products : recherchez les produits en stock avec alerte activée dont la quantité est inférieure ou égale au seuil, avec des informations sur la pénurie.
search_product_sales : renvoie les ventes agrégées de produits, limitées, classées par valeur.
create_product : créez un produit matérialisé ou dématérialisé simple à l’aide d’identifiants de catégorie et d’unité existants.
import_products : importer de manière atomique entre 1 et 50 produits simples, avec résolution de la catégorie et de l’unité.

Clients et fournisseurs

search_customers : recherchez par nom, e-mail ou téléphone.
get_customer : récupérer un client et les totaux de compte.
create_customer : crée un client et des adresses de facturation ou de livraison facultatives.
create_provider : crée un fournisseur/prestataire à partir des champs de contact autorisés.

Commandes, finance et reporting

search_orders : recherchez par code de commande, période de dates ou statut de paiement.
get_order : récupérer une commande et ses articles.
search_wallet_history : récupérer les entrées de relevé du portefeuille client dans des limites définies.
get_dashboard_summary : renvoie les totaux des paiements effectués, impayés, partiellement payés, de la taxe et des revenus pour une période donnée.
generate_report : crée un rapport PDF/aperçu HTML avec une marque, ou une exportation CSV à partir de sections de rapport délimitées.

Oxen a également mis à disposition des ressources de référence sûres pour la configuration actuelle du magasin, les types de paiement, les catégories de produits et les groupes de taxes. Codex peut utiliser ces ressources pour choisir des identifiants valides et formater les résultats pour le magasin connecté.

Espace réservé à l’image : une conversation dans un codex montrant une demande en lecture seule de faible stock, l’appel d’outil Oxen et un court tableau de résultats avec caviardage.

Lire des actions par rapport à écrire des actions

Les recherches, les consultations, 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.

Avant d’approuver un appel d’écriture, examinez chaque champ affiché par Codex. En particulier :

Vérifiez les noms, les prix, les codes-barres, les SKU, les identifiants de catégorie, les groupes d’unités et les paramètres de taxe.
Utilisez un identifiant d’idempotence unique (idempotency_key) pour chaque écriture prévue. Si une requête doit être réessayée, réutilisez la même clé afin qu’une nouvelle tentative réseau ne crée pas de doublon.
Confirmez les coordonnées du client et du prestataire avant de les transmettre.
Testez les autorisations d’écriture avec un enregistrement temporaire clairement nommé uniquement si la politique de votre boutique le permet, puis supprimez-le ultérieurement de NexoPOS si nécessaire.
N’oubliez pas que import_products est atomique : tout le lot est annulé si une ligne échoue.

Une invite en deux étapes, sûre, est :

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.

Espace réservé d’image : une capture d’écran de Codex affichant une action create_product proposée et en attente d’approbation, avec des identifiants spécifiques au magasin masqués.

Demandes pratiques après la configuration

Une fois que les vérifications en lecture seule fonctionnent, Codex peut traiter des questions en plusieurs étapes, telles que :

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.

Dépannage

Les bœufs n’apparaissent pas dans /mcp

Confirmez que le fichier de configuration s’appelle exactement .codex/config.toml pour une configuration à portée du projet, ou config.toml sous ~/.codex pour une configuration à portée de l’utilisateur.
Assurez-vous que le projet est approuvé.
Redémarrez l’application de bureau ChatGPT ou l’extension IDE après avoir modifié les paramètres MCP.
Exécutez « codex mcp list » et « codex mcp --help » depuis un terminal.
Validez la syntaxe TOML, en particulier les antislashs Windows et les guillemets dans http_headers_helper.

Le serveur renvoie une erreur 401 Unauthorized (non autorisé)

Vérifiez que le TOKEN existe dans token.env et qu’il ne contient aucun espace accidentel.
Si vous utilisez bearer_token_env_var, vérifiez que OXEN_TOKEN est défini dans l’environnement à partir duquel Codex a été lancé.
Si vous utilisez l’assistant, exécutez-le directement et confirmez qu’il produit un seul objet JSON compact. N’affichez pas et ne partagez pas la sortie, car elle contient le jeton d’accès (bearer).
Réémettez le jeton s’il a été révoqué, expiré ou exposé.

Le serveur renvoie une erreur 403 Forbidden (interdit)

Le jeton est reconnu, mais ne dispose pas des autorisations nécessaires pour la capacité demandée, ou bien la politique du magasin le bloque. Demandez à l’administrateur de NexoPOS d’accorder uniquement l’étendue (scope) requise. Ne contournez pas la limite d’autorisation en plaçant des identifiants de magasin ou des informations d’identification dans l’invite.

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

C’est normalement un problème d’autorisations, et non un échec de connexion. Oxen expose des outils à portée des autorisations ; ainsi, un jeton en lecture seule peut volontairement omettre create_product, create_customer, create_provider ou import_products.

L’application de bureau se connecte, mais ChatGPT web ne fonctionne pas.

C’est attendu. Les clients Local Codex partagent la configuration MCP de l’hôte, mais ChatGPT web ne lit pas le fichier local .codex/config.toml. ChatGPT web nécessite une extension installée qui regroupe ou se connecte au serveur MCP distant et peut également être contrôlée par les administrateurs de l’espace de travail.

La connexion expire.

Confirmez que https://nexocloud.dev/mcp/oxen est accessible depuis l’ordinateur.
Vérifiez les règles du proxy, du pare-feu et du DNS.
Augmentez startup_timeout_sec si la connexion est lente.
Gardez tool_timeout_sec suffisamment élevé pour la génération du rapport, qui peut prendre plus de temps qu’une simple recherche.

Checklist de sécurité

Gardez token.env hors de Git et des sauvegardes destinées à être partagées.
Ne collez jamais un jeton dans une invite Codex.
Ne mettez jamais le jeton directement dans config.toml.
Utilisez HTTPS et le point de terminaison Oxen exact.
Accordez les autorisations d’outil les plus limitées possible.
Conservez les approbations de l’outil d’écriture activées.
Examiner les projets de rédaction avant de les approuver.
Révoquez et remplacez tout jeton qui aurait pu être exposé.
Utilisez des jetons distincts pour les magasins de production et de test.
Supprimez ou désactivez l’entrée MCP lorsque l’accès n’est plus nécessaire.

Déconnecter Oxen

Pour désactiver le serveur sans supprimer ses paramètres :

[mcp_servers.oxen]
enabled = false

Alternativement, supprimez la section [mcp_servers.oxen] et redémarrez Codex. Effacez la variable d’environnement du shell actuelle avec :

Remove-Item Env:OXEN_TOKEN

Si l’ordinateur ou le dépôt change de propriétaire, révoquez également le jeton.