<!--
  Full-page Markdown export (rendered HTML → GFM).
  Source: https://neotoma.io/ca/neotoma-with-codex-connect-remote-http-oauth
  Generated: 2026-04-28T13:35:40.683Z
-->
# Codex remote setup (HTTP with OAuth)

[Neotoma with Codex](/neotoma-with-codex) · Remote setup for Codex sandboxes that cannot run local Neotoma.

Running Codex on the same machine as Neotoma? See [Codex local setup (stdio)](/neotoma-with-codex-connect-local-stdio).

* * *

## Setup

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](https://ngrok.com/download) or [Cloudflare Tunnel (cloudflared)](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) installed on your machine. Install one:
    
    Code snippet
    
    Copy the exact snippet shown below.
    
    ```
    # 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](https://dashboard.ngrok.com/get-started/your-authtoken). You can set the token as an environment variable instead of running `ngrok config`:
    
    Code snippet
    
    Copy the exact snippet shown below.
    
    ```
    # 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)
    
    Code snippet
    
    Copy the exact snippet shown below.
    
    ```
    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
    
    Code snippet
    
    Copy the exact snippet shown below.
    
    ```
    # .codex/config.toml
    [mcp_servers.neotoma]
    type = "http"
    url = "https://<tunnel-host>/mcp"
    ```
    
    Codex handles the [MCP OAuth authorization flow](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization) automatically.
    

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

[Back to Neotoma with Codex](/neotoma-with-codex) · [Install guide](/install) · [MCP reference](/mcp)