Skip to content
Help Center
Submit a request Sign in

Tags

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  ·  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

Before starting, install Codex CLI through the official installation route or your IT team. Obtain the MCP server URL and your agent-bound token from Supportbench Settings → API → MCP AI Tokens → New Token → Codex → Choose agent → Create token and continue. Keep the token private. If the connection already works, use it rather than creating a duplicate.

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. Check that Codex CLI is installed

Paste this command at the terminal prompt and press Enter:

codex mcp list

Read the result. “Not recognized” or “command not found” means the CLI is not available here; finish installation or ask IT before continuing. Inspect an existing Supportbench connection before adding another.

3. Add the Supportbench server

Copy the full MCP server URL from the Supportbench wizard. Replace the placeholder inside the quotes, 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.

4. 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.

5. Start the Codex conversation before asking for a case

At the ordinary terminal prompt, run:

codex

Sign in to Codex if requested. 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.

6. 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.”

7. 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.

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.

ComputerOpen the terminalRecognize the right place
WindowsOpen 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.
macOSOpen Spotlight, type Terminal, and open Terminal.You will see a text prompt with a cursor ready for a command.
Managed work computerUse the terminal and installation process approved by IT.If the application or installation is blocked, give IT the requirement rather than changing security settings.
  1. Click beside the terminal’s prompt. Copy one command line at a time, paste it, then press Enter.
  2. Do not copy a leading prompt such as PS C:\…>, explanatory text, or Markdown backticks. The command examples here contain only the command.
  3. Read the result before entering the next line. An error means that step has not completed successfully.
  4. 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

  1. Open Settings, expand API, and choose MCP AI Tokens.
  2. Choose New Token. The Connect an AI client wizard opens.
  3. At Choose AI, select the application you intend to use. For the Codex procedures below, select Codex.
  4. At Choose agent, choose the intended Supportbench agent. Recheck the identity before selecting Create token and continue. This action creates a credential.
  5. 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.
  6. Complete one client procedure below. The URL tells the client where to connect; the agent token is used separately to authorize it.
  7. 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.”

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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 seeWhat it usually meansWhat to do next
codex is not recognized / command not foundThe 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 placeholderThe 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 existsA 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 authorizationLogin 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 unsupportedThe 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 absentConfiguration 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 deniedThe 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 failsA 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 unsupportedThe 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 errorThe 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?