Install Codex

Codex reaches StateLode through statelode-bridge, a small stdio server launched with npx. Codex config is TOML, not JSON — the bridge is registered as an [mcp_servers.statelode] table in ~/.codex/config.toml.

You’ll need Node.js installed, since the bridge runs through npx — see The statelode-bridge CLI.

On the Codex desktop app? You can skip the bridge and the token entirely. Go to Settings → MCP servers → Connect to a custom MCP, choose the Streamable HTTP tab, enter https://api.statelode.dev/mcp, and sign in with Connect with StateLode (OAuth) when prompted — the app stores and refreshes the credential for you. The Codex CLI can’t use that path: MCP servers in config.toml are stdio-only, so the CLI connects through the bridge with a token, below.

1. Mint a token

Create a StateLode API token in the dashboard. The bridge takes it as a --token argument, inlined into the config below — so the CLI and the desktop app work identically, with no shell variable to inherit. Keep the config file out of git — see Token security. Don’t hand the token to the Codex agent in chat — though you can ask it to open ~/.codex/config.toml so you paste the table and token in yourself (Let the agent open the file).

2. Add the server

Add an [mcp_servers.statelode] table to ~/.codex/config.toml (or scope it to a single project with .codex/config.toml):

[mcp_servers.statelode]
command = "npx"
args = ["statelode-bridge", "--token", "paste-your-token-here"]

Codex only reads [mcp_servers.*] tables from config.toml. If you copied a { "mcpServers": ... } JSON block from another tool’s guide, that won’t work here — Codex ignores JSON.

Prefer the desktop app’s UI? Go to Settings → MCP servers → Connect to a custom MCP, choose the STDIO tab, and enter Command npx with Arguments statelode-bridge, --token, <your token> — the same server, no TOML editing.

Verify

Restart Codex so it picks up the new server, then ask:

Use StateLode to list active tasks for project statelode, then get the highest priority task.

Codex should call task_search first and only call task_get after choosing a task summary.

Troubleshooting

• Server never connects — confirm Node.js is installed and on your PATH (node --version); the bridge launches through npx.
• initialize fails / empty response — double-check the token in args is a current, unrevoked token from the dashboard.
• TOML vs JSON — Codex only reads [mcp_servers.*] tables from config.toml. A JSON { "mcpServers": ... } block won’t be parsed.
• url is not supported for stdio — you wrote a url = "…" block under [mcp_servers.statelode]. In config.toml, MCP servers are stdio-only (command/args), so Codex rejects url. Use the bridge command form above. The app’s Streamable HTTP tab is a separate, GUI-managed path — it doesn’t map to a hand-written url= table.
• Connects in the CLI but not in one repo (or vice-versa) — a project-scoped .codex/config.toml overrides your global ~/.codex/config.toml. If a repo has its own [mcp_servers.statelode] table, fix it there too.