Skip to content

Connecting Codex

Codex connects to the MCP server over HTTPS at the Resource URL set on the Model Context Protocol (MCP) page, and signs in through the QIE console. The Codex CLI, the Codex IDE extension and the ChatGPT desktop app share one Codex configuration, so a server added in one is available in the others. This page covers adding the server, signing in and out, and settings that keep a session safe.

Adding the server

Add the server with its Resource URL:

codex mcp add qie --url https://qie.example.com:8443/mcp

The same entry can be written in the Codex configuration file, ~/.codex/config.toml:

[mcp_servers.qie]
url = "https://qie.example.com:8443/mcp"

In the IDE extension, open the gear menu, select MCP servers, select Add server, enter a name, choose Streamable HTTP, enter the Resource URL, save, and select Restart extension.

Codex does not sign in when the Issuer URL on the Model Context Protocol (MCP) page names the console by a private IP address, such as https://10.0.1.4:8180/qie. Codex then does not use QIE's sign-in address: codex mcp list shows its Auth as Unsupported, and signing in fails with Registration failed and HTTP 405 Method Not Allowed. Name the console by a host name the computer running Codex resolves, such as https://qie.example.com:8180/qie, with a server certificate that names it (see Deploying the MCP Server).

The name you give the server, qie here, is the name Codex shows for it and the prefix of its tools, such as mcp__qie__get_object. When one person connects to more than one engine, use the environment label in the name, such as qie-prod and qie-test, the same form get_instance_info reports. codex mcp list lists the servers Codex knows, and /mcp in a Codex session shows the ones in use.

Signing in

Adding the server signs in at once: codex mcp add finds that QIE supports sign-in, prints the address of QIE's approval page and opens it in your browser, and says Successfully logged in. once you approve. To sign in again later, for example after signing out, run:

codex mcp login qie

In the IDE extension, select Authenticate beside the server in the MCP server list. Codex then:

  1. Reads where to sign in from QIE's protected resource document, at the address QIE names in its answer to a request that is not signed in.
  2. Identifies itself to QIE. While Metadata Document Hosts on the Model Context Protocol (MCP) page lists any host, QIE tells clients it accepts client details documents, and Codex uses its own, which is on chatgpt.com; add chatgpt.com to the list then, or the sign-in is refused. While the list is empty, Codex registers with QIE, under the name Codex. See MCP Client Sign-In.
  3. Opens the QIE console's approval page in your browser. Sign in to the console if you are not signed in, choose the access to grant and click Approve.

After you approve, the browser returns to Codex through an address on your own computer (127.0.0.1), and Codex collects its tokens from QIE. The port is one the operating system picks, unless the mcp_oauth_callback_port setting fixes one. QIE accepts only such addresses as return addresses for MCP clients.

Access to grant

The approval page offers read-only access by default. Grant the narrowest access the work needs: read only for looking at channels, messages and logs, manage for starting and stopping channels and working error queues, and full access only for changing configuration. Whatever access Codex asks for, the approval page selects Read only, and you choose.

A tool that needs wider access than you granted is refused. To grant wider access, run codex mcp login qie again and choose it on the approval page.

Confirmations

Actions that cannot be undone, such as deleting, purging or importing, ask you to confirm in Codex. When Codex asks whether to run the tool, as it does with the settings under Recommended permissions, QIE's question appears as a second one; the action goes ahead only when you accept both. Whether Codex shows QIE's question or rejects it depends on its approval settings: under a granular approval_policy, the mcp_elicitations option lets these questions through instead of rejecting them. A rejected question cancels the action, so nothing changes; the next attempt asks again.

When Require client confirmation is on, QIE refuses these actions to a client that cannot ask its user at all.

Let Codex run QIE's read tools without asking, and have it ask before every tool that changes QIE. QIE cannot protect a session whose client approves changes without asking.

The server's default_tools_approval_mode setting decides which of its tools Codex asks about. QIE marks every tool that changes something as not read-only, so the writes value does this. Add it to the server's entry in ~/.codex/config.toml:

[mcp_servers.qie]
url = "https://qie.example.com:8443/mcp"
default_tools_approval_mode = "writes"

With writes, Codex asks before each tool that is not marked read-only, including the tools QIE marks as destructive, such as purging messages. Leave approvals_reviewer at its default, user: set to auto_review, it hands eligible approvals to a reviewing agent instead of you.

Guides and prompts

Codex reads QIE's guides, such as qie://guide/zone-objects, by itself when a task needs them. Codex does not use MCP prompts, so QIE's prompts are not in its / command list. Ask for the same work in your own words, such as "Work the error queue of channel ADT In."

Signing out

Codex keeps a server's tokens in your operating system's keyring, or, where no keyring is available, in .credentials.json in the Codex home folder (~/.codex by default), which other programs running as you can read. The mcp_oauth_credentials_store setting chooses between them. Treat the tokens like a password: whoever holds them can use QIE as you, with the access you granted.

To sign out, run:

codex mcp logout qie

Codex deletes the tokens it keeps for the server, but does not revoke them at QIE, so the sign-in stays active there. To end it, revoke it under MCP Sign-Ins in Edit My Profile (see Your own sign-ins), or ask an administrator to revoke it on the Model Context Protocol (MCP) page.

Long results

QIE limits each result to the Read Cap (bytes) on the Model Context Protocol (MCP) page, 40,000 bytes by default, and returns the rest in parts (see MCP Tool Results and Errors). Codex shortens a tool result that is longer than its output budget, which by default comes from the model. The output_token_limit setting for one tool, under [mcp_servers.qie.tools.<tool>], sets that tool's budget. The top-level tool_output_token_limit setting sets the token budget for storing each tool output in Codex's history.