OneHazel Docs

Appearance

For LLMsView as Markdown·

Install in Codex ​

What you need before you start

  • Codex installed. In a terminal, codex --version prints a version number.
  • A key with the Connect scope, mcp_connect_enabled. Only Connect casino > Integrate with AI > Create integration key makes one. The API Keys page lists it with the label mcp-connect. The MCP switch on the API Keys page is a different setting and cannot add this scope.
  • That key in the ONEHAZEL_API_KEY variable, from steps 1 and 2 of Install.

Step 1. Open the Codex settings file ​

Codex keeps its servers in a file called ~/.codex/config.toml. Each command below opens it, and creates it first if it is missing.

On a Mac, in Terminal:

bash
mkdir -p ~/.codex && touch ~/.codex/config.toml && open -e ~/.codex/config.toml

On Linux, in a terminal:

bash
mkdir -p ~/.codex && nano ~/.codex/config.toml

On Windows, in PowerShell:

powershell
New-Item -ItemType Directory -Force "$HOME\.codex" | Out-Null; notepad "$HOME\.codex\config.toml"

What you should see

A text editor with the file open. It may be empty, or hold settings you already had.

Step 2. Paste the OneHazel block and save ​

Add this at the end of the file, then save. In nano, save with Ctrl+O and Enter, then leave with Ctrl+X.

toml
[mcp_servers.onehazel]
url = "https://api.onehazel.com/mcp-server"
bearer_token_env_var = "ONEHAZEL_API_KEY"

What each line means, in the words of the Codex documentation (learn.chatgpt.com, Model Context Protocol page, read on 2026-10-16):

  • url: "(required): The server address."
  • bearer_token_env_var: "(optional): Environment variable name for a bearer token to send in Authorization."

The file holds the variable's name, not your key, so it is safe to keep.

What you should see

The file ends with the three lines above. If the file already had a [mcp_servers.onehazel] section, keep only one.

Step 3. Start Codex from the window that holds your key ​

Use the same terminal window where you set ONEHAZEL_API_KEY. Go to your casino's code folder and start Codex. Replace the path with your own folder:

bash
cd ~/path/to/your-casino-code
codex

What you should see

Codex opens in that folder.

Step 4. Check the connection ​

Inside Codex, type /mcp. From a terminal, codex mcp list shows the same list.

What you should see

A server called onehazel in the list. Its tools include connect_status.

If onehazel is missing, Codex did not read the file. Check the file name, and check you saved it. If it is listed but every call fails, the key is missing in this window. Repeat step 2 of Install.

Step 5. Paste the one line ​

In the Codex chat, paste exactly:

text
Connect my casino to OneHazel. Start with connect_status and follow next_step.

What you should see

Codex calls connect_status and reports one line per module. Continue with the journey.

Other ways to set it up ​

  • One project only. Put the same block in .codex/config.toml inside the project folder. Codex reads it only in projects you have marked as trusted.
  • If your network blocks the direct connection. Use the OneHazel bridge instead. It is a small program that runs on your computer and passes messages between Codex and the OneHazel server. It takes your key from the environment, so the key never sits in the file. The Codex documentation describes env_vars as "(optional): Environment variables to allow and forward."
toml
[mcp_servers.onehazel]
command = "npx"
args = ["-y", "@onehazel/mcp"]
env_vars = ["ONEHAZEL_API_KEY"]

Use one of the two blocks, never both.