Connect Supportbench to Codex CLI: terminal commands for first-time users

Updated Wednesday, October 28, 2026 · Marc Staine

To connect Supportbench to Codex CLI, enter the setup commands in your computer’s terminal, authorize the connection in the browser, then run codex to start the AI conversation before asking it to read a known case. CLI means command-line interface. A terminal is the window where a command runs when you press Enter; it is different from the AI conversation. This procedure explains each stage without assuming you already use command-line tools.

At a glance

For: support operators setting up Codex CLI for the first time. Applies to: Supportbench Core.

Start here: Supportbench Settings → API → MCP AI Tokens, then your computer’s terminal

The complete setup sequence · Install Codex CLI and fix “codex is not recognized” · How do I open a terminal and run a CLI command? · Create the connection in Supportbench · Connect with Codex CLI, step by step · First test: read one case and verify the answer · If you would prefer to use buttons · Use the connection in your first support handoff · Troubleshoot setup and daily use · What to give IT or Supportbench if setup fails

The complete setup sequence

Start with a computer where your organization permits Codex and an approved Codex sign-in. Your Supportbench administrator must also permit MCP access for the agent you will use. If the connection already works, use it rather than creating a duplicate. The installation instructions below cover a computer with no Codex CLI installed.

1. Open your computer’s terminal

On Windows, open Start, search for Windows Terminal or PowerShell, and open it. On macOS, open Spotlight and launch Terminal. A terminal displays a text prompt and cursor.

2. Install the CLI if it is missing

Run codex --version. If a version is displayed, continue to step 3. If the command is not recognized and your organization permits installation, run the appropriate official installer below. On Windows, use PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

On macOS, use Terminal:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Wait for completion, close and reopen the terminal, then run codex --version again. Continue only when a version is displayed. The installation and recovery section explains each action and common errors.

3. Get the Supportbench connection details

In Supportbench, open Settings → API → MCP AI Tokens → New Token → Codex → Choose agent → Create token and continue. Copy the wizard’s MCP server URL and retain your agent-bound token privately. If you cannot access these settings, ask your administrator to arrange an authorized connection. Do not use another agent’s token.

4. Add the Supportbench server

Run codex mcp list and inspect any existing Supportbench entry first. To add a new entry, replace the placeholder inside the quotes with the full MCP server URL from the wizard, paste the completed command into the terminal, and press Enter:

codex mcp add supportbench --url "PASTE-THE-WIZARD-URL-HERE"

Use the actual server URL, not the literal placeholder or portal homepage. The agent token does not go in this command.

5. Authorize Supportbench in the browser

Run this separate terminal command:

codex mcp login supportbench

In the browser page it opens, enter your own Supportbench agent token in the requested token field and approve the connection. Return to the terminal and check that login succeeded.

6. Start the Codex conversation before asking for a case

At the ordinary terminal prompt, run:

codex

Sign in to your approved Codex account if requested. This is separate from authorizing Supportbench. You are now using the active Codex conversation inside the terminal. Enter /mcp there to inspect the connection. Do not enter the natural-language case request at an ordinary PowerShell or shell prompt.

7. Ask Codex to read a known case

In the active Codex conversation, use this request after replacing the example ID with a case you can already open:

Read-only first request

“Use Supportbench to read case c-12345. Show its subject, company, owner, status and link. Do not change it.”

8. Compare the result with Supportbench

Open the returned case link and verify the identity and facts. Only then treat the connection as tested. The Supportbench wizard’s Verify/Done screen is a checklist, not a connectivity test.

The sections below explain the same sequence in more detail. If you completed it, do not create another token or repeat Add/login just to read the explanations.

Install Codex CLI and fix “codex is not recognized”

If PowerShell says “codex is not recognized,” or Terminal says “command not found,” your current terminal cannot find the Codex CLI program. Adding an MCP server cannot fix that. Install the CLI first, then return to the connection steps. Having a desktop application or a browser account does not establish that the codex terminal command is available.

Windows: install from a new PowerShell window

Open Start, type PowerShell, and open it. If you use Windows Terminal, choose a PowerShell tab. You should see a prompt such as PS C:\Users\YourName>. The folder name varies; do not type that prompt.
Check your organization’s software-installation policy. If IT manages application installation, give them the official Codex CLI link and ask them to install the command for your Windows user. Otherwise continue with the official installer below.
Copy the entire Windows command below. Paste it into the PowerShell window, then press Enter once. This command downloads and runs OpenAI’s installer; it is not a question to paste into Co-Pilot.
Wait for installation to finish and read its final message. If it reports an error, use the troubleshooting table below before proceeding.
Close that PowerShell window and open a new one. This lets the new window pick up changes to the locations Windows searches for commands. Run codex --version and press Enter. A version number confirms that the program can run in this terminal.

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

The -ExecutionPolicy ByPass option is part of OpenAI’s published installer command and applies to the PowerShell process it starts. It does not authorize bypassing your organization’s installation rules. If managed policy or endpoint protection blocks the installer, give IT the error and official link; do not disable protection or repeatedly rerun the command as administrator.

macOS: install from Terminal

Press Command + Space, type Terminal, and press Enter.
If your organization allows this installation, paste the macOS/Linux command below into Terminal and press Enter. It downloads and runs OpenAI’s installer.
Wait for completion, reopen Terminal, then run codex --version. Continue only after the command returns a version.

curl -fsSL https://chatgpt.com/codex/install.sh | sh

These are the standalone installation routes published on the official Codex CLI installation page, checked for this guide. That page also lists npm and Homebrew alternatives. Use one installation route agreed with IT; adding a second installation while diagnosing a missing command can make it harder to identify which copy runs.

Verify each stage separately

Check	What it proves	What it does not prove
`codex --version` returns a version	The CLI is installed and reachable in this terminal.	You are signed in or Supportbench is connected.
Codex starts and its sign-in completes	Your approved Codex account can start a conversation.	The separate Supportbench agent token has been authorized.
`codex mcp list` lists Supportbench	A server entry exists in this CLI configuration.	The server is reachable or a particular record is authorized.
Codex reads a known case and you compare it with Supportbench	The connection can retrieve that authorized record accurately.	Every record or write action is permitted.

Recover from installation problems

What you see	What to do next
“codex is not recognized” after installation	Open a new PowerShell window and retry `codex --version`. If it still fails, confirm the installer completed under your current user and ask IT to check the installed location and PATH. PATH is the list of locations the terminal searches for programs.
A download, proxy, certificate or access-denied error	Save the exact non-secret error and ask IT to check the approved download route and device policy. Do not proceed to MCP setup until the CLI runs.
“npm is not recognized” while following another guide	That guide uses an npm installation route. The standalone route above avoids making npm setup a prerequisite; use the route your organization supports.
A `>>` continuation prompt instead of a result	PowerShell may be waiting for a missing quote or unfinished command. Press Ctrl + C to cancel that unfinished input, then paste the full single-line command again with straight quotation marks.
The command appears as a message in an AI chat	Open PowerShell or Terminal and run it at the computer’s prompt. A setup command typed into a chat is not itself an installation.
Codex starts but sign-in fails	Installation and account access are separate. Use the approved sign-in method for your Codex account. Your Supportbench agent token belongs only in the Supportbench authorization page.

For a first support task, start Codex in an empty work folder approved by your organization. The CLI can work with local files as well as connected tools. Keep unrelated customer exports out of that folder and review the requested permissions. You do not need to create application code to ask a Supportbench MCP question.

How do I open a terminal and run a CLI command?

A command is a line of text that tells a program what to do. The terminal displays a prompt, waits for your input, and shows the result after you press Enter. You do not need to understand programming to enter the commands below, but the named program must be installed first.

Computer	Open the terminal	Recognize the right place
Windows	Open Start, type Windows Terminal or PowerShell, and open the installed application.	You will see a text prompt, often beginning with PS and a folder path, with a cursor after it.
macOS	Open Spotlight, type Terminal, and open Terminal.	You will see a text prompt with a cursor ready for a command.
Managed work computer	Use the terminal and installation process approved by IT.	If the application or installation is blocked, give IT the requirement rather than changing security settings.

Click beside the terminal’s prompt. Copy one command line at a time, paste it, then press Enter.
Do not copy a leading prompt such as PS C:\…>, explanatory text, or Markdown backticks. The command examples here contain only the command.
Read the result before entering the next line. An error means that step has not completed successfully.
When a command opens a browser for authorization, complete that browser step, then return to the terminal.

If someone says “run this command”

They mean paste the command into this terminal and press Enter. They do not mean paste it into Your Co-Pilot, a customer reply, the browser address bar, or the Codex conversation. Later, when this guide says “ask the AI,” use the AI conversation instead.

Create the connection in Supportbench

Open Settings, expand API, and choose MCP AI Tokens.
Choose New Token. The Connect an AI client wizard opens.
At Choose AI, select the application you intend to use. For the Codex procedures below, select Codex.
At Choose agent, choose the intended Supportbench agent. Recheck the identity before selecting Create token and continue. This action creates a credential.
At Connect, keep the newly created agent token private and copy the MCP server URL from the client card. Copy the complete value; do not substitute the public documentation URL.
Complete one client procedure below. The URL tells the client where to connect; the agent token is used separately to authorize it.
Return to the wizard and select I completed setup. The Verify step is a checklist, not a connectivity test. Run the read-only test below in the actual AI client, then select Done.

If your team already has a working bearer-token or OAuth connection, retain it unless the administrator intends to replace it. Do not revoke a working token while another person or scheduled workflow still depends on it.

Connect with Codex CLI, step by step

Install Codex CLI using the current official Codex installation instructions for your operating system, or ask IT to install it. Installing the desktop app does not establish that the codex command is available in the terminal. If a fresh terminal reports “not recognized” or “command not found,” finish CLI installation before continuing.

1. Inspect existing connections. In the terminal, enter:

codex mcp list

If an existing Supportbench connection already works, use it. If the command is not recognized, see troubleshooting below. The list establishes configuration; it does not prove a case can be retrieved.

2. Add the server. Copy the full server URL from the Supportbench wizard. In the following command, replace PASTE-THE-WIZARD-URL-HERE with that value and keep the quotation marks:

codex mcp add supportbench --url "PASTE-THE-WIZARD-URL-HERE"

The word supportbench is the local connection name. --url tells Codex that the next value is the server address. No agent token appears in this command. Do not run it with the placeholder still present. If the name already exists, inspect the existing connection instead of repeatedly adding another one.

3. Authorize the connection. Enter:

codex mcp login supportbench

The browser opens the Supportbench authorization flow. Paste the agent token from the wizard into the requested field there and approve. Do not fill a manual OAuth client-ID or client-secret field with that token. Return to the terminal and read the result. If it reports failure, the connection is not ready even if a browser page opened.

4. Start or return to Codex. If you are still at the ordinary terminal prompt, run codex and sign in to Codex if prompted. Inside the active Codex conversation, enter /mcp to inspect active servers. These are different sign-ins: your Codex account opens the AI application; Supportbench authorization grants the specific support connection.

5. Ask for a known record. Use the test in the next section. Official command reference: Codex MCP configuration and commands.

First test: read one case and verify the answer

Open your chosen test case in Supportbench first. Replace the example ID below with that case’s actual ID. The example is deliberately read-only: it does not send a message, assign an agent, or close anything.

Copy and adapt this first request

“Use the Supportbench connection to read case c-12345. Do not change it. Tell me its case ID, subject, company, current owner or queue, status, and latest recorded customer update. Link the case and state any information you could not retrieve.”

Check that the client actually invokes a Supportbench tool rather than answering from general knowledge. If the tool requires read approval, inspect its target and approve the intended read.
Compare the returned ID, subject, company, and owner with the open case. If the ID resolves to the wrong organization or a similarly named record, correct the scope before continuing.
Open the returned link and compare the latest relevant activity. A compact tool response may include only recent context; ask for earlier activities when the task requires the whole investigation.
If access is denied or the record is absent, check the bound agent and its permissions. Do not grant broader access simply to make a test pass.
After this succeeds, try a small company search and a knowledge search. A successful single-case read does not establish that every reporting or writing capability is available.

Record the client, workspace, bound agent, test case, test time, and outcome in your team’s connection handover. Keep credentials out of that record.

If you would prefer to use buttons

Use the desktop MCP settings route in the complete Supportbench MCP guide when your installed client offers it. A terminal is not required for that route. Do not mix instructions for ChatGPT in a browser with the local CLI: configuring one surface does not establish that the other can access the connection.

Use the connection in your first support handoff

Choose an existing case with a known outcome or a safe training record. Ask Codex to read its activities and draft an internal handoff with the customer impact, attempted fixes, unresolved questions, current owner, and next update commitment. Tell it to link evidence and make no changes.

Compare the draft with the case. If a detail is absent from the history, the useful result is “not recorded,” followed by a proposed question—not an invented answer. After you review the draft, decide whether to save it as an internal activity through your normal case process. Reading a case and drafting text do not transfer its ownership.

A useful second request

“Read case c-12345 and the relevant activities. Draft the internal specialist handoff. Separate facts from hypotheses and suggested next steps. Link the evidence. Do not send or save anything.” Replace the example ID with the real case.

Troubleshoot setup and daily use

What you see	What it usually means	What to do next
codex is not recognized / command not found	The terminal cannot find Codex CLI.	Install it through the official/IT-approved route, open a fresh terminal, and retry the connection-list command. Do not paste the command into the AI chat as a workaround.
The command contains the example placeholder	The actual server address was never supplied.	Copy the complete MCP server URL from the wizard and replace the placeholder inside the quotes.
A server with this name already exists	A local configuration is already present.	Inspect it and test whether it works before replacing it. Avoid duplicate credentials and unexplained connection names.
The browser does not complete authorization	Login or callback did not finish.	Keep the terminal open, use any authorization link actually shown by the client, and complete the flow on the same machine. Record the non-secret error if it still fails.
Automatic registration unsupported	The requested OAuth registration path failed.	Give the error reference and client version to your administrator. Do not invent client credentials or use your agent token as a client secret.
Server listed, but tools absent	Configuration exists but connection/startup or authorization is incomplete.	Check enabled/authenticated state, restart the client connection as its UI instructs, then inspect active tools and run the known-case test.
Some records work and others are denied	The agent’s access or selected scope differs.	Compare the exact record with the bound agent’s normal access. Review division, team, role and record restrictions.
A previously working connection fails	A credential may have expired, been revoked, or lost its intended access.	Ask the administrator to inspect the existing token and agent before creating a replacement.
The answer is fluent but unsupported	The assistant may not have retrieved enough evidence.	Request source records, dates, scope and missing facts. Verify before sending it to a customer.
A write appears stuck or returns an unclear error	The result may be uncertain.	Read the target record before retrying; preserve the tool outcome for investigation.

What to give IT or Supportbench if setup fails

Which application and operating system you are using: desktop app, CLI, or browser.
The step that failed and the exact non-secret error text.
Whether codex mcp list runs and whether Supportbench appears.
Whether authorization opened and completed, and whether the known-case test can read any record.
The intended Supportbench account and bound agent identity, supplied through your approved support channel.

Remove tokens, authorization codes, passwords and private case content from screenshots. Do not repeatedly create tokens while troubleshooting an existing one. If a write was attempted and its outcome is unclear, inspect the target record before retrying.

Was this article helpful?