Connect OpenAI Codex to StackJack

The OpenAI Codex CLI connects to remote MCP servers and can sign in over OAuth (MCP is the Model Context Protocol, the open standard AI tools use to call external tools). Note: Codex Cloud (codex.openai.com) has no MCP support — this guide applies to the Codex CLI and IDE extension only.

Prerequisites

• Codex CLI installed (a current build with the codex mcp command group).
• A StackJack account that is a member of your workspace. Any team member can connect — no admin-created credentials needed for the sign-in path.
• Your StackJack MCP endpoint URL. Copy it from the MCP Setup page in the portal — that card shows the address for your workspace's region. The examples in this guide use the US address, https://mcp.stackjack.io/mcp; other regions have their own hostname. See Your region and your endpoint.

Connect with sign-in (recommended)

1. Add the server by URL, sign in, and verify:

   Copy code

   codex mcp add stackjack --url https://mcp.stackjack.io/mcp
   codex mcp login stackjack
   codex mcp list
   

2. codex mcp login opens a browser — use the same email, password, and MFA you use for the StackJack Portal.

The OAuth token is managed by Codex; it is not written to config.toml.

Manual credentials (headless / CI fallback)

An owner, co-owner, or Administrator creates an MCP client in the portal first (see Managing MCP credentials).

Codex reads the credential from an environment variable, so it never has to sit in config.toml. Where that variable comes from is your decision, and it is the part that matters. Two warnings first:

• Base64 is encoding, not encryption. Anyone who reads the encoded string can decode it back to the client id and secret. Treat the encoded value as the secret itself.
• A shell profile is a plaintext file, and a typed command lands in shell history. Pasting the credential into ~/.zshrc moves it out of config.toml and into another readable file on the same machine — it does not make it unstored. Do not describe that as "not stored anywhere".

1. Put the value in STACKJACK_AUTH, from a source appropriate to the machine:

   Environment	Where to keep it
   CI or a scheduled job	The platform's secret store, injected into the environment for that job. Never a literal in the workflow file
   A shared or managed workstation	The operating system's credential manager or keychain, read into the variable at session start
   Your own machine, no secret store available	A file readable only by you, with an accepted risk that it is plaintext on disk

   The value's shape is the word Basic, a space, then base64 of client_id:client_secret. Produce the encoding in a way that keeps the secret out of your shell history.

2. Reference the variable from ~/.codex/config.toml — the env_http_headers section reads it at runtime, so the credential is not written into this file:

   Copy code

   [mcp_servers.stackjack]
   url = "https://mcp.stackjack.io/mcp"
   enabled = true
   tool_timeout_sec = 120
   
   [mcp_servers.stackjack.env_http_headers]
   "Authorization" = "STACKJACK_AUTH"
   

Use env_http_headers (not bearer_token_env_var) for this: bearer_token_env_var prepends Bearer and is only suitable for bearer tokens, while StackJack manual credentials use a Basic authorization value.

Tool limits

Codex does not publish a hard MCP tool cap, but StackJack can expose hundreds of tools depending on your connectors and plan. Keep the list focused by connecting through a client with a restricted tool selection, or switch StackJack to compact catalog mode so it serves a small tool list and Codex discovers the rest on demand. An admin must first enable catalog modes for your organization on the Settings page; until then StackJack serves the full tool list. See Choosing tools for each client and managing harness tool limits.

Troubleshooting

• You're using Codex Cloud — MCP is not available there; use the Codex CLI or IDE extension.
• Header fallback fails after a shell restart — the STACKJACK_AUTH export wasn't persisted to your shell profile.
• Sign-in says no account was found — sign up in the portal first, or ask your team admin for an invite.
• For anything else, see Connection troubleshooting.