Codex remote setup (HTTP with OAuth)

Codex sandboxes can connect to remote MCP servers over HTTP. Use this when Neotoma is not installed locally in the sandbox. Start with local install on your host machine, then configure remote access:

1. Install a tunnel provider — Neotoma's --tunnel flag needs either ngrok or Cloudflare Tunnel (cloudflared) installed on your machine. Install one:

   # ngrok (via Homebrew)
   brew install ngrok
   ngrok config add-authtoken <YOUR_NGROK_TOKEN>
   
   # — or Cloudflare Tunnel —
   brew install cloudflared

   ngrok requires a free account and auth token from dashboard.ngrok.com. You can set the token as an environment variable instead of running ngrok config:

   # In your shell profile or .env
   export NGROK_AUTHTOKEN=<YOUR_NGROK_TOKEN>

   Cloudflare Tunnel works without an account for quick tunnels. If both providers are installed, Neotoma auto-detects which to use; pass --tunnel-provider ngrok or --tunnel-provider cloudflare to choose explicitly.

2. Start the API server with a tunnel — the --tunnel flag auto-provisions a public HTTPS URL via ngrok or Cloudflare (whichever is installed)

   neotoma api start --env prod --tunnel

   The tunnel URL is printed to the console and written to /tmp/ngrok-mcp-url.txt. You can also use a reverse proxy or your own domain instead of --tunnel.

3. Configure HTTP transport with OAuth in your Codex config — replace the URL with your tunnel URL

   # .codex/config.toml
   [mcp_servers.neotoma]
   type = "http"
   url = "https://<tunnel-host>/mcp"

   Codex handles the MCP OAuth authorization flow automatically.

When MCP is not available in the sandbox, agents can use the neotoma CLI directly as a fallback.