Why Codex's setup is different from every other IDE
Claude Code, Cursor, Windsurf, and Gemini CLI all take MCP server config as JSON, just with different key names inside it. OpenAI's Codex CLI is the outlier: its config file is TOML, and a JSON snippet pasted in verbatim will not parse. If you've already wired up MCP in another tool and copy the same block into ~/.codex/config.toml, it fails immediately — not because the URL or key is wrong, but because the file format is wrong.
The actual config: ~/.codex/config.toml
[mcp_servers.wkfgo]
url = "https://YOUR_INSTANCE/api/mcp"
http_headers = { "Authorization" = "Bearer wk_YOUR_KEY" }
That's the whole block. mcp_servers.wkfgo is a table header — everything under it until the next [...] header belongs to this server. Get the wk_… key from Settings → Integrations → Connect your AI IDE in WKFGo; it's a personal key scoped to your own FeatureAccess, not an admin credential to share across the team.
First call
Start codex in a project directory and ask it to use the tool directly:
"Call list_tasks and show me what's assigned to me in the Backend project."
If Codex reports it has no wkfgo tools available, the usual cause is a TOML syntax error — a missing quote or a stray comma copied from a JSON example is enough to make the whole file fail to parse, which silently drops every server defined in it, not just this one. Validate the file with any TOML linter before assuming the WKFGo side is broken.
Where this fits a terminal-first workflow
Codex CLI's model is different from an in-editor chat panel — it's closer to a scripted agent you point at a task and let run. That changes which WKFGo tools matter most:
get_context_packat the start of a session, so Codex has acceptance criteria before it starts changing files, not after.update_progressat natural checkpoints — a terminal session with no visible board means progress is invisible unless something reports it.submit_for_reviewat the end, so a fully unattended run still leaves a reviewable trail instead of just a diff and a shrug.
A useful pattern for longer unattended runs: open with get_task to fetch the full description and comments, not just the title — Codex CLI sessions tend to run longer between human checkpoints than a chat-panel IDE, so front-loading context matters more here than it does in Cursor or Windsurf.
Common mistakes
Pasting JSON into a TOML file. This is the single most common failure and it produces no useful error from WKFGo's side — the file simply doesn't parse. Copy the TOML block above, not a JSON one from another IDE's docs.
Forgetting the quotes around the header value. http_headers = { "Authorization" = "Bearer ..." } needs the inner keys quoted; TOML inline tables are stricter about this than JSON.
Running long unattended sessions without get_context_pack first. A model that starts editing without acceptance criteria will produce plausible-looking code that doesn't match what the task actually asked for — the cost of that mismatch is higher in an unattended terminal session than in an interactive chat where a human can redirect mid-stream.
FAQ
Does Codex CLI need write access to actually update tasks, or can it just read? Both are the same connection — what the key can do is governed by FeatureAccess on the project, same as a human login. Start with a read-scoped role if you want Codex observing before it writes.
Is the MCP server different between Codex, Cursor, and Claude Code?
No — it's the same /api/mcp endpoint and the same tool catalog for every client; only the config file format changes per IDE.
Can I run Codex against a self-hosted WKFGo instance?
Yes, the url in the TOML points at your instance's /api/mcp — cloud or self-hosted makes no difference to Codex.