Common problems and where to look. When in doubt, read the startup banner — it reports the effective config, every discovered/bridged MCP server, and every failure.

• Is the server still running? The process must stay up for connector discovery and every tool call. If you started it from the wizard's "start now" step, keep that terminal open.
• Native tunnel: does the banner say ready? It reports ready only after /readyz passes and a control-plane poll succeeds. If not, check the runtime key and tunnel ID.
• Right tunnel ID? In ChatGPT the connector must select the same tunnel ID Codex Free reports. Set Connection type: Tunnel and Authentication: None (native mode).
• External mode: is your proxy up and pointing at port 3000, with the connector URL ending in /mcp?

• Onboard the chat: ChatGPT Web isn't reliable about reading instructions. Open with "Call get_agent_brief and follow it for the rest of this chat." If it drifts, ask for the brief again.
• Multi-project: project-scoped tools are unavailable until you bind a project. Call set_project_root (exact path) or list_projects (by intent) first. See Multi-Project Mode .
• import_host_file gone? It's removed when artifactIngress.enabled is false.
• Large bridged tool set not surfacing? Some clients (ChatGPT included) won't show many bridged tools — use gateway mode. See Bridging MCP Servers .

Check the banner first. The most common cause is a wrong command path:

Upstream MCP servers:
 idasql -> FAILED: could not launch 'D:/wrong/path.exe': The system cannot find the path specified.

• A failed upstream is skipped, never blocking startup or native tools.
• disabled: true shows as -> disabled.
• OAuth-only servers need a bearer token via bearerTokenEnvVar or an env-backed Authorization header — OAuth login isn't implemented.
• Legacy SSE/WebSocket transports are rejected explicitly.
• Missing plugin-provided servers? The CLI discovery step may have failed — the banner warns. Pass --codex-cli to make it mandatory, or set codexMcp.useCli.

run_command only runs allowedCommands; exec_command also allows exec.extraAllowedCommands. The allowlist is checked at every command position, and command substitution ($(...), backticks) is rejected outright. Add the binary to the right list, or set exec.mode: "unrestricted" if you fully trust the caller. See Security Model .

That's intentional. Tools stop at a budget and say so on the last line:

(showing lines 1-1000 of 4820 — call again with offset=1000 for the rest)

Call again with the named argument (offset, etc.). Raise the caps in the output block if you must. See Context and Memory .

The shell is picked by name from $SHELL (not the host platform). Starting from Git Bash on Windows gets bash; starting from PowerShell gets PowerShell. Override with exec.defaultShell or a per-call shell argument. Check get_environment to see what's active. See Tools Reference .

• Task state persists in ~/.codex-free/projects/<name>-<hash>/memory.json — a new chat picks it up via instructions, or one recall. If memory.enabled is false, nothing is saved.
• Multi-project bindings live in ~/.codex-free/conversation-projects/. A conversation can't switch projects — start a new chat. A stale/missing project fails closed. Delete the binding file to clear it.

That's what worktrees are for. In multi-project mode with mode: auto, the second chat gets its own managed worktree. If you set mode: never, they share the checkout. See Worktree Isolation .

Turn up logging:

codex-free -v --work-dir /path/to/project # debug
codex-free -vv --work-dir /path/to/project # trace
RUST_LOG=codex_free=trace,rmcp=warn codex-free --work-dir /path/to/project # protocol level

And consider an Audit Logging to see the exact sequence of tool calls (shapes and timings, no payloads).

• FAQ for conceptual questions.
• Open an issue with your startup banner (redact secrets) and what you expected.