Cómo conectar NexoPOS a Codex (ChatGPT) con Oxen

Oxen conecta una tienda NexoPOS con Codex mediante el Model Context Protocol (MCP). Después de configurar la conexión, Codex puede usar las herramientas de NexoPOS permitidas por el token de Oxen; por ejemplo, para buscar productos, revisar artículos con bajo stock, resumir ventas, consultar pedidos y, cuando esté permitido, crear registros.

Esta guía cubre la aplicación de escritorio local de ChatGPT (Codex), la CLI de Codex y la extensión de Codex para IDE. Estos clientes comparten la configuración de MCP en el mismo host de Codex. ChatGPT en la web no lee la configuración local de Codex de una computadora; los usuarios de la web necesitan un complemento instalado que proporcione la conexión remota de MCP.

Qué conexión hace

La ruta de datos es:

Tu solicitud en Codex → servidor Oxen MCP → tu tienda autorizada de NexoPOS

Oxen proporciona las herramientas y el contexto de tienda de confianza. Codex decide qué herramienta llamar a partir de tu solicitud, Oxen verifica los permisos del token y NexoPOS devuelve el resultado permitido. El token determina qué tienda y capacidades están disponibles, por lo que nunca se debe agregar manualmente un identificador de tienda a un prompt o a una llamada de herramienta.

El endpoint de Oxen utilizado en esta guía es:

https://nexocloud.dev/mcp/oxen

Oxen utiliza HTTP transmisible y autenticación mediante token portador. Durante la verificación de esta guía, el endpoint completó un enlace MCP como Oxen 2.0.0 usando la versión de protocolo 2025-06-18.

Requisitos

Antes de comenzar, asegúrate de que tienes:

Una instalación funcional de NexoPOS conectada a Nexo Cloud/Oxen.
Un token de acceso de Oxen con los permisos necesarios para las tareas previstas.
La aplicación de escritorio de ChatGPT con Codex, Codex CLI o la extensión Codex IDE.
Un proyecto local de confianza si quieres que la configuración se aplique solo a un proyecto.

Los ejemplos a continuación asumen que el proyecto contiene un archivo privado token.env con esta estructura:

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

No pegues el token real en documentación, prompts, capturas de pantalla, commits ni en config.toml.

Protege el token primero

Agrega token.env al .gitignore del proyecto antes de confirmar cualquier archivo del proyecto:

token.env

Si el token ya se ha confirmado o compartido, eliminar el archivo del último commit no es suficiente porque puede permanecer en el historial de Git. Revoca el token expuesto en NexoPOS/Nexo Cloud, emite uno de reemplazo y, luego, actualiza token.env.

Usa los permisos de tokens más restringidos que cubran el trabajo del usuario. Un flujo de trabajo de informes normalmente solo necesita permisos de lectura de herramientas; no debería recibir automáticamente permisos de creación de clientes, proveedores o productos.

Opción 1: Conectar con una variable de entorno

Este es el ajuste más sencillo para Codex CLI o para un IDE lanzado desde la misma sesión de terminal.

1. Cargar token.env en PowerShell

Abre PowerShell en el directorio del proyecto y ejecuta:

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

Esto establece OXEN_TOKEN solo para el proceso actual de PowerShell y los programas que se inician desde él. Al cerrar la terminal, se borra.

2. Agrega la configuración de MCP

Crea o actualiza .codex/config.toml en el proyecto:

[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 configuración de MCP con alcance del proyecto se carga solo para proyectos confiables. Para que el servidor esté disponible en cada proyecto local, coloca la misma tabla en la configuración del usuario en ~/.codex/config.toml en su lugar.

default_tools_approval_mode = "writes" permite que las herramientas de solo lectura se ejecuten normalmente, mientras solicita la aprobación antes de las herramientas que no estén marcadas como de solo lectura. Mantén esta configuración a menos que la política de tu organización requiera que se apruebe cada llamada.

3. Inicia Codex desde el mismo terminal

Inicie el cliente desde la sesión de PowerShell que contiene OXEN_TOKEN. Para Codex CLI:

códice

Si se inicia un IDE desde un acceso directo diferente o desde un proceso ya en ejecución, es posible que no herede la variable de entorno temporal. Reinícielo desde la terminal preparada o use la Opción 2.

Opción 2: Permitir que Codex lea token.env mediante un helper de encabezado

Esta opción es conveniente para la aplicación de escritorio de ChatGPT porque no depende de que la aplicación herede una variable temporal de terminal. Codex admite un comando local http_headers_helper para servidores HTTP en streaming. El comando debe imprimir un objeto JSON que contenga los encabezados de la solicitud.

1. Crea un script de ayuda de encabezado local

Crea tools/Get-OxenHeaders.ps1 con el siguiente contenido:

$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

El script solo imprime el JSON de encabezado que Codex necesita. No agregues salida de diagnóstico porque el texto adicional haría que la respuesta del asistente no sea válida.

2. Configura el servidor Oxen

Agrega esto a .codex/config.toml, reemplazando la ruta con la ruta absoluta al script auxiliar:

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

Usa solo un método de autorización. Elimina bearer_token_env_var cuando uses http_headers_helper; una fuente explícita de token bearer tiene prioridad sobre el encabezado Authorization proporcionado por el helper.

3. Confianza y reinicio

Abre el proyecto en la aplicación de escritorio de ChatGPT y confíalo cuando se te solicite. Luego reinicia Codex para que recargue la configuración de MCP. En la aplicación de escritorio, la ruta de interfaz de usuario equivalente es Configuración → Servidores de MCP. El flujo de configuración oficial es agregar un servidor, elegir Streamable HTTP, proporcionar su URL, guardar y reiniciar.

Verifica la conexión

En la aplicación de escritorio de ChatGPT o en la interfaz de terminal de Codex, ingresa:

/mcp

Confirma que los bueyes están habilitados y conectados. En una terminal fuera de la TUI de Codex, también puedes ejecutar:

codex mcp list

Marcador de imagen: Una captura de pantalla del panel /mcp que muestra a Oxen como habilitado y conectado. Recorta los servidores y la información de la cuenta que no estén relacionados.

Luego comienza con una solicitud inofensiva y de solo lectura:

Usa Oxen para mostrarme cinco productos. Devuelve solo el nombre de cada producto, su SKU y el stock actual.

Otros avisos de verificación útiles incluyen:

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.

Codex debería mostrar una llamada a la herramienta Oxen y almacenar los datos devueltos. Si responde usando solo conocimiento general sin llamar a Oxen, indica explícitamente “Usa el servidor MCP de Oxen” y vuelve a comprobar /mcp.

Capacidades disponibles de los bueyes

La lista exacta depende de los permisos del token. El servidor verificado expuso estas herramientas:

Productos e inventario

search_products: busca productos por nombre, SKU o código de barras.
get_product: recuperar un producto por su identificador numérico.
get_low_stock_products: encuentra existencias con alertas activadas en o por debajo de su umbral, con información de escasez.
buscar_ventas_de_productos: devuelve las ventas agregadas de productos acotadas ordenadas por valor.
create_product: crea un producto materializado o desmaterializado único y sencillo utilizando los identificadores de categoría y unidad existentes.
import_products: importar de forma atómica entre 1 y 50 productos simples, con resolución de categoría y unidad.

Clientes y proveedores

buscar_clientes: buscar por nombre, correo electrónico o teléfono.
get_customer: recuperar un cliente y los totales de la cuenta.
create_customer: crea un cliente y direcciones de facturación o envío opcionales.
create_provider: crea un proveedor/proveedor de servicios a partir de los campos de contacto permitidos.

Pedidos, finanzas y reportes

search_orders: busca por código de pedido, rango de fechas o estado de pago.
get_order: recuperar un pedido y sus artículos.
search_wallet_history: recuperar entradas acotadas del extracto de la cartera del cliente.
get_dashboard_summary: devuelve los totales de pagado, no pagado, parcialmente pagado, impuestos e ingresos para un rango de fechas.
generate_report: crear un informe con marca en PDF/HTML (vista previa) o exportar a CSV desde secciones del informe acotado.

Oxen también expuso recursos de referencia seguros para la configuración actual de la tienda, los tipos de pago, las categorías de productos y los grupos de impuestos. Codex puede usar esos recursos para elegir identificadores válidos y dar formato a los resultados para la tienda conectada.

Marcador de imagen: Una conversación del Códice que muestra una solicitud de bajo stock en modo solo lectura, la llamada a la herramienta Oxen y una breve tabla de resultados con partes ocultas.

Leer acciones versus acciones de escritura

Las búsquedas, consultas, resúmenes y lecturas de recursos de referencia no modifican NexoPOS. Las herramientas de creación e importación sí lo hacen.

Antes de aprobar una llamada de escritura, revisa cada campo que muestre Codex. En particular:

Verifique nombres, precios, códigos de barras, SKU, identificadores de categoría, grupos de unidades y la configuración de impuestos.
Usa un idempotency_key único para cada escritura prevista. Si una solicitud debe reintentarse, reutiliza la misma clave para que un reintento de red no cree un duplicado.
Confirme los datos de contacto del cliente y del proveedor antes de transmitirlos.
Prueba los permisos de escritura con un registro temporal con un nombre claramente identificable solo cuando la política de tu tienda lo permita, y elimínalo más tarde de NexoPOS si corresponde.
Recuerda que import_products es atómico: todo el lote se revierte cuando falla cualquier fila.

Un aviso seguro de dos pasos es:

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.

Marcador de imagen: una captura de pantalla de Codex que muestra una acción create_product propuesta y en espera de aprobación, con identificadores específicos de la tienda ocultos.

Solicitudes prácticas después de la configuración

Una vez que las comprobaciones de solo lectura funcionen, Codex puede manejar preguntas de varios pasos, como:

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.

Solución de problemas

Los bueyes no aparecen en /mcp

Confirma que el archivo de configuración se llama exactamente .codex/config.toml para una configuración con alcance de proyecto o config.toml en ~/.codex para una configuración con alcance de usuario.
Asegúrate de que el proyecto sea de confianza.
Reinicia la aplicación de escritorio de ChatGPT o la extensión del IDE después de cambiar la configuración de MCP.
Ejecuta `codex mcp list` y `codex mcp --help` desde una terminal.
Valida la sintaxis de TOML, especialmente las barras invertidas de Windows y las comillas en http_headers_helper.

El servidor devuelve 401 No autorizado

Comprueba que TOKEN existe en token.env y que no tiene espacios accidentales.
Si usa bearer_token_env_var, confirme que OXEN_TOKEN está definido en el entorno desde el que se inició Codex.
Si usa el helper, ejecútelo directamente y confirme que produce un único objeto JSON compacto. No muestre ni comparta la salida porque contiene el token de portador.
Reemita el token si fue revocado, caducó o quedó expuesto.

El servidor devuelve 403 Forbidden

El token se reconoce, pero no tiene permisos para la capacidad solicitada, o la política de la tienda lo bloquea. Pida al administrador de NexoPOS que conceda únicamente el alcance requerido. No eluda el límite de permisos colocando identificadores de la tienda o credenciales en el mensaje.

Las herramientas de lectura funcionan, pero faltan las herramientas de creación

Esto normalmente es un problema de permisos, no un fallo de conexión. Oxen expone herramientas con alcance de permisos, por lo que un token de solo lectura puede omitir intencionalmente create_product, create_customer, create_provider o import_products.

La aplicación de escritorio se conecta, pero la web de ChatGPT no.

Se espera esto. Los clientes Local Codex comparten la configuración MCP del host, pero ChatGPT web no lee el archivo local .codex/config.toml. ChatGPT web requiere un complemento instalado que agrupe o se conecte al servidor MCP remoto y que, además, puede estar controlado por administradores del espacio de trabajo.

La conexión se agota el tiempo de espera.

Confirma que https://nexocloud.dev/mcp/oxen es accesible desde el ordenador.
Verifica las reglas del proxy, el firewall y el DNS.
Aumenta startup_timeout_sec si la conexión es lenta.
Mantén tool_timeout_sec lo suficientemente alto para la generación del informe, que puede tardar más que una búsqueda simple.

Lista de verificación de seguridad

Mantén token.env fuera de Git y de las copias de seguridad destinadas a compartirse.
Nunca pegues un token en un prompt de Codex.
Nunca pongas el token directamente en config.toml.
Usa HTTPS y el endpoint exacto de Oxen.
Concede los permisos de herramienta más limitados posible.
Mantén habilitadas las aprobaciones de la herramienta de escritura.
Revisa los borradores propuestos antes de aprobarlos.
Revoca y reemplaza cualquier token que pueda haber sido expuesto.
Usa tokens separados para los almacenes de producción y de pruebas.
Elimina o deshabilita la entrada de MCP cuando ya no se necesite acceso.

Desconectar Oxen

Para desactivar el servidor sin eliminar su configuración:

[mcp_servers.oxen]
enabled = false

Alternativamente, elimina la sección [mcp_servers.oxen] y reinicia Codex. Borra la variable de shell actual con:

Remove-Item Env:OXEN_TOKEN

Si el equipo o el repositorio está cambiando de propietario, revoca también el token.