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.
For project creation, use an explicitly named workspace first, then this repo's statelode.json workspaceId, then the active/default workspace. One accessible workspace needs no prompt; if several remain ambiguous, ask before writing. State the chosen workspace and offer a quick switch before creation.
Finish only after you verify the MCP connection, discover the workspace and projects, and make the current repo ready to use StateLode with both workspaceId and projectId pinned.

Codex should inspect and preserve your existing config, run the commands below, and verify the connection. Your part is limited to browser sign-in and consent, plus restarting the app if the running agent cannot safely do that itself.

Connect with StateLode

Current Codex releases support remote Streamable HTTP MCP and OAuth directly in both the CLI and desktop app. The stdio bridge and a static token are not required for normal interactive use.

1. Add the remote server

Run this from any directory:

codex mcp add statelode --url https://api.statelode.dev/mcp

The command writes the user-level MCP entry that the CLI and app share. Its equivalent TOML in ~/.codex/config.toml is:

[mcp_servers.statelode]
url = "https://api.statelode.dev/mcp"

Do not add an Authorization header for OAuth. StateLode’s 401 response advertises the protected-resource metadata Codex uses to discover the browser sign-in flow.

2. Sign in with OAuth

Adding the server does not complete authentication. Trigger OAuth explicitly:

codex mcp login statelode

Codex opens the StateLode browser flow. Sign in, choose the workspace access this connection should receive, and approve consent. Codex stores and refreshes the resulting credential; there is no StateLode token to paste into TOML or chat.

3. Verify

codex mcp get statelode

The server should report the remote URL above and OAuth support. If the Codex desktop app was already open, restart it so the running process reloads the connection, 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.

Static token (headless and CI only)

Use a static credential only for a non-interactive machine that cannot complete browser OAuth. Keep the value in the machine’s secret store as STATELODE_TOKEN; never put the literal in config.toml, a repository file, a command argument, or chat.

Register the same remote server with the environment-variable reference:

codex mcp add statelode --url https://api.statelode.dev/mcp --bearer-token-env-var STATELODE_TOKEN

Equivalent TOML:

[mcp_servers.statelode]
url = "https://api.statelode.dev/mcp"
bearer_token_env_var = "STATELODE_TOKEN"

statelode-bridge remains a compatibility transport for older or genuinely stdio-only MCP runtimes. It is not the primary path for current Codex releases.

Troubleshooting

• Needs authentication or a 401 — run codex mcp login statelode. Do not replace OAuth with a static token merely because the browser step has not happened yet.
• An old command = "npx" StateLode entry remains — remove only that statelode MCP registration, then rerun the HTTP mcp add and mcp login commands above. Never print the old command arguments while inspecting it; they may contain a credential.
• Works in one surface but not the other — the CLI and app share the config, but an already running app must be restarted after the entry or OAuth credential changes.
• codex mcp add does not accept --url — update Codex. Until that environment can be updated, use the compatibility bridge and a machine-scoped static credential.