Install Codex

Let your agent do the setup

Paste this into Codex:

Set up StateLode in this coding environment.
Read and follow https://statelode.dev/docs/agent-setup/
First tell me which client and which surface you are running in — for example a terminal CLI or a desktop app. Ask me if you cannot tell from the environment, and do not guess: for some clients the surface changes the config and the sign-in step.
Do every setup step you can yourself. Do not ask me to edit config files, run commands you can run, or paste secrets into chat.
Pause only for browser sign-in or OAuth consent, a client restart you cannot safely perform yourself, or a genuinely ambiguous client, surface, or project choice. Give me one exact action, wait for me to finish it, then continue.
Finish only after you verify the MCP connection, discover the workspace and projects, and make the current repo ready to use StateLode.

Codex should handle the config and verification. You handle only browser consent, a restart it cannot perform, or direct placement of a bridge token when the CLI path requires one. The steps below are the manual fallback and troubleshooting reference.

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.