Como Conectar o NexoPOS ao Codex (ChatGPT) com Oxen

A Oxen conecta uma loja NexoPOS ao Codex por meio do Model Context Protocol (MCP). Após a conexão ser configurada, o Codex pode usar as ferramentas do NexoPOS permitidas pelo token da Oxen — por exemplo, para encontrar produtos, revisar itens com baixo estoque, resumir vendas, consultar pedidos e, quando permitido, criar registros.

Este guia abrange o aplicativo desktop local do ChatGPT (Codex), a CLI do Codex e a extensão do Codex IDE. Esses clientes compartilham a configuração do MCP no mesmo host do Codex. O ChatGPT na web não lê a configuração local do Codex de um computador; usuários da web precisam de um plugin instalado que forneça a conexão remota do MCP.

Qual é a conexão?

O caminho dos dados é:

Seu pedido no Codex → servidor MCP Oxen → sua loja NexoPOS autorizada

A Oxen fornece as ferramentas e o contexto confiável da loja. O Codex decide qual ferramenta chamar a partir da sua solicitação, a Oxen verifica as permissões do token e a NexoPOS retorna o resultado permitido. O token determina quais loja e capacidades estão disponíveis; portanto, um identificador de loja nunca deve ser adicionado manualmente a um prompt ou a uma chamada de ferramenta.

O endpoint de Oxen usado neste guia é:

https://nexocloud.dev/mcp/oxen

A Oxen usa HTTP Streamable e autenticação por token bearer. Durante a verificação deste guia, o endpoint concluiu um handshake MCP como Oxen 2.0.0 usando a versão do protocolo 2025-06-18.

Requisitos

Antes de começar, certifique-se de que você tem:

Uma instalação NexoPOS em funcionamento conectada ao Nexo Cloud/Oxen.
Um token de acesso do Oxen com as permissões necessárias para as tarefas pretendidas.
O aplicativo de desktop do ChatGPT com o Codex, o Codex CLI ou a extensão do Codex IDE.
Um projeto local confiável se você quiser que a configuração seja aplicada apenas a um projeto.

Os exemplos abaixo assumem que o projeto contém um arquivo privado token.env com esta estrutura:

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

Não cole o token real na documentação, em prompts, capturas de tela, commits ou no config.toml.

Proteja o token primeiro

Adicione o token.env ao .gitignore do projeto antes de fazer commit de quaisquer arquivos do projeto:

token.env

Se o token já tiver sido confirmado (commitado) ou compartilhado, remover o arquivo do commit mais recente não é suficiente, pois ele pode permanecer no histórico do Git. Revogue o token exposto no NexoPOS/Nexo Cloud, emita um substituto e, em seguida, atualize o token.env.

Use as permissões de token mais restritas possíveis que cubram o trabalho do usuário. Um fluxo de trabalho de relatórios normalmente só precisa de permissões de leitura para ferramentas; ele não deve receber automaticamente permissões de criação de clientes, fornecedores ou produtos.

Opção 1: Conectar com uma variável de ambiente

Esta é a configuração mais simples para o Codex CLI ou para uma IDE iniciada na mesma sessão de terminal.

1. Carregue o token.env no PowerShell

Abra o PowerShell no diretório do projeto e execute:

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

Isso define OXEN_TOKEN apenas para o processo atual do PowerShell e para os programas iniciados a partir dele. Fechar o terminal o limpa.

2. Adicione a configuração do MCP

Crie ou atualize o arquivo .codex/config.toml no projeto:

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

A configuração do MCP com escopo do projeto é carregada apenas para projetos confiáveis. Para disponibilizar o servidor em todo projeto local, coloque a mesma tabela na configuração do usuário em ~/.codex/config.toml.

default_tools_approval_mode = "writes" permite que ferramentas somente leitura sejam executadas normalmente, enquanto solicita aprovação antes de ferramentas que não estejam marcadas como somente leitura. Mantenha esta configuração, a menos que a política da sua organização exija que todas as chamadas sejam aprovadas.

3. Inicie o Codex no mesmo terminal

Inicie o cliente na sessão do PowerShell que contém OXEN_TOKEN. Para o Codex CLI:

códice

Se um IDE for iniciado a partir de um atalho diferente ou de um processo já em execução, ele pode não herdar a variável de ambiente temporária. Reinicie-o a partir do terminal preparado ou use a Opção 2.

Opção 2: Permitir que o Codex leia o token.env por meio de um helper de cabeçalho

Esta opção é conveniente para o aplicativo de desktop do ChatGPT porque não depende de o aplicativo herdar uma variável temporária de terminal. O Codex oferece um comando local http_headers_helper para servidores HTTP compatíveis com streaming. O comando deve imprimir um objeto JSON contendo os cabeçalhos da solicitação.

1. Crie um script de helper de cabeçalho local

Crie o arquivo tools/Get-OxenHeaders.ps1 com o seguinte conteúdo:

$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

O script imprime apenas o JSON de cabeçalho de que o Codex precisa. Não adicione saída de diagnóstico, pois texto extra tornaria a resposta do helper inválida.

2. Configure o servidor Oxen

Adicione isto a .codex/config.toml, substituindo o caminho pelo caminho absoluto para o 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"

Use apenas um método de autorização. Remova bearer_token_env_var ao usar http_headers_helper; uma fonte explícita de token bearer tem precedência sobre um cabeçalho Authorization fornecido pelo helper.

3. Confiança e reinício

Abra o projeto no aplicativo desktop do ChatGPT e confie nele quando solicitado. Em seguida, reinicie o Codex para recarregar a configuração do MCP. No aplicativo desktop, o caminho equivalente na interface é Configurações → Servidores MCP. O fluxo oficial de configuração é adicionar um servidor, escolher HTTP transmitível, fornecer a URL, salvar e reiniciar.

Verifique a conexão

No aplicativo de desktop do ChatGPT ou na interface do terminal do Codex, digite:

/mcp

Confirme que o oxen está habilitado e conectado. Em um terminal fora do Codex TUI, você também pode executar:

codex mcp list

Espaço reservado para imagem: Uma captura de tela do painel /mcp mostrando a Oxen como ativada e conectada. Recorte servidores e informações de conta não relacionados.

Então comece com uma solicitação inofensiva e somente leitura:

Use Oxen para me mostrar cinco produtos. Retorne apenas o nome de cada produto, o SKU e o estoque atual.

Outros prompts de verificação úteis incluem:

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.

O Codex deve mostrar uma chamada de ferramenta do Oxen e armazenar os dados retornados. Se ele responder com base em conhecimento geral sem chamar o Oxen, diga explicitamente “Use o servidor MCP do Oxen” e verifique novamente em /mcp.

Capacidades disponíveis do Oxen

A lista exata depende das permissões do token. O servidor verificado disponibilizou estas ferramentas:

Produtos e inventário

search_products: encontre produtos pelo nome, SKU ou código de barras.
get_product: recuperar um produto por seu identificador numérico.
get_low_stock_products: encontre produtos com estoque baixo com alertas ativados e com quantidade igual ou inferior ao limite, com informações de falta.
search_product_sales: retorne as vendas agregadas de produtos limitadas, classificadas por valor.
create_product: crie um produto materializado ou desmaterializado simples usando identificadores existentes de categoria e unidade.
import_products: importar de forma atômica entre 1 e 50 produtos simples, com resolução de categoria e unidade.

Clientes e fornecedores

search_customers: pesquisar por nome, e-mail ou telefone.
get_customer: recuperar um cliente e os totais da conta.
create_customer: crie um cliente e endereços opcionais de cobrança ou entrega.
create_provider: criar um fornecedor/prestador a partir dos campos de contato permitidos.

Pedidos, finanças e relatórios

search_orders: pesquise por código do pedido, intervalo de datas ou status de pagamento.
get_order: recuperar um pedido e seus itens de linha.
search_wallet_history: recuperar entradas limitadas do extrato da carteira do cliente.
get_dashboard_summary: retorne totais pagos, não pagos, parcialmente pagos, impostos e renda para um intervalo de datas.
generate_report: criar um relatório em PDF/visualização HTML com marca ou exportação CSV a partir de seções do relatório delimitado.

A Oxen também disponibilizou recursos de referência seguros para a configuração atual da loja, tipos de pagamento, categorias de produtos e grupos de impostos. O Codex pode usar esses recursos para escolher identificadores válidos e formatar os resultados para a loja conectada.

Um placeholder de imagem: uma conversa do Codex mostrando uma solicitação somente leitura de baixo estoque, a chamada de ferramenta do Oxen e uma breve tabela de resultados com trechos ocultos.

Ler ações versus escrever ações

As pesquisas, consultas, resumos e leituras de recursos de referência não modificam o NexoPOS. As ferramentas de criação e importação fazem isso.

Antes de aprovar uma chamada de escrita, revise todos os campos exibidos pelo Codex. Em particular:

Verifique nomes, preços, códigos de barras, SKUs, IDs de categoria, grupos de unidades e configurações de impostos.
Use uma chave de idempotência exclusiva (idempotency_key) para cada gravação pretendida. Se uma solicitação precisar ser reenviada, reutilize a mesma chave para que uma nova tentativa de rede não crie um duplicado.
Confirme os dados de contato do cliente e do fornecedor antes de transmiti-los.
Teste permissões de escrita com um registro temporário claramente nomeado apenas quando a política da sua loja permitir e remova-o posteriormente do NexoPOS, se for apropriado.
Lembre-se de que o import_products é atômico: todo o lote é revertido quando qualquer linha falha.

Um prompt seguro em duas etapas é:

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.

Espaço reservado de imagem: Uma captura de tela do Codex exibindo uma ação create_product proposta e aguardando aprovação, com identificadores específicos da loja ocultados.

Solicitações práticas após a configuração

Assim que as verificações somente leitura funcionarem, o Codex pode lidar com perguntas de várias etapas, 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.

Solução de problemas

Os bois não aparecem em /mcp

Confirme que o arquivo de configuração é chamado exatamente de .codex/config.toml para uma configuração com escopo do projeto ou de config.toml em ~/.codex para uma configuração com escopo do usuário.
Certifique-se de que o projeto é confiável.
Reinicie o aplicativo de desktop do ChatGPT ou a extensão do IDE após alterar as configurações do MCP.
Execute o comando `codex mcp list` e o comando `codex mcp --help` em um terminal.
Validar a sintaxe do TOML, especialmente as barras invertidas do Windows e as aspas em http_headers_helper.

O servidor retorna 401 Não autorizado

Verifique se o TOKEN existe no arquivo token.env e se não tem espaços acidentais.
Se estiver usando bearer_token_env_var, confirme que OXEN_TOKEN está definido no ambiente que iniciou o Codex.
Se estiver usando o helper, execute-o diretamente e confirme que ele gera um único objeto JSON compacto. Não exiba nem compartilhe a saída porque ela contém o token bearer.
Reemita o token se ele tiver sido revogado, tiver expirado ou tiver sido exposto.

O servidor retorna 403 Forbidden

O token é reconhecido, mas não tem permissão para a capacidade solicitada, ou a política da loja o bloqueia. Peça ao administrador do NexoPOS para conceder apenas o escopo necessário. Não contorne o limite de permissões colocando identificadores da loja ou credenciais no prompt.

As ferramentas de leitura funcionam, mas as ferramentas de criação estão ausentes

Isso normalmente é um problema de permissão, não uma falha de conexão. A Oxen expõe ferramentas com escopo de permissões, portanto um token somente leitura pode intencionalmente omitir create_product, create_customer, create_provider ou import_products.

O aplicativo de desktop conecta, mas o ChatGPT na web não.

Isso era esperado. Os clientes Local Codex compartilham a configuração do MCP do host, mas o ChatGPT web não lê o arquivo local .codex/config.toml. O ChatGPT web requer um plugin instalado que agrupe ou se conecte ao servidor MCP remoto e também pode ser controlado por administradores do workspace.

A conexão expira.

Confirme que https://nexocloud.dev/mcp/oxen está acessível a partir do computador.
Verifique as regras de proxy, firewall e DNS.
Aumente o startup_timeout_sec se a conexão estiver lenta.
Mantenha o tool_timeout_sec alto o suficiente para a geração do relatório, que pode levar mais tempo do que uma pesquisa simples.

Checklist de segurança

Mantenha o token.env fora do Git e de backups destinados a compartilhamento.
Nunca cole um token em um prompt do Codex.
Nunca coloque o token diretamente no config.toml.
Use HTTPS e o endpoint Oxen exato.
Conceda as permissões de ferramenta mais restritas possíveis.
Mantenha as aprovações da ferramenta de escrita ativadas.
Revise os textos propostos antes de aprová-los.
Revogue e substitua quaisquer tokens que possam ter sido expostos.
Use tokens separados para as lojas de produção e de teste.
Remova ou desative a entrada do MCP quando o acesso não for mais necessário.

Desconectar Oxen

Para desativar o servidor sem excluir suas configurações:

[mcp_servers.oxen]
enabled = false

Como alternativa, remova a seção [mcp_servers.oxen] e reinicie o Codex. Limpe a variável de ambiente atual com:

Remove-Item Env:OXEN_TOKEN

Se o computador ou o repositório estiver mudando de proprietário, revogue também o token.