Use Klio with Codex

Connect OpenAI Codex to Klio over streamable HTTP. Keep the token in an environment variable so it never lands in a config file.

Codex works from your terminal and reads AGENTS.md for its standing instructions. Connect it to Klio and those instructions can say "all work goes through the board": Codex claims a story, builds it against its acceptance criteria, hands you anything only you can do and sends the story to review, so a run never ends with "I think it's done".

Connect by signing in

Codex supports MCP sign-in, so there's no token to copy. You approve it in Klio and choose which projects it can reach; disconnect it any time in Settings → Agents.

  1. Add the server and sign in

    codex mcp login opens Klio's approval screen in your browser and stores the result for Codex.

    terminal
    codex mcp add klio --url https://klio.dev/api/mcp
    codex mcp login klio

Or connect with a token

For setups where you'd rather paste a token, or a version of Codex without sign-in.

!Before you start: create a token in Klio under Settings → Connect agents, and use it in place of klio_YOUR_TOKEN.
  1. Export your token

    Put this in your shell profile (~/.zshrc or ~/.bashrc).

    terminal
    export KLIO_TOKEN=klio_YOUR_TOKEN
  2. Add the server

    Either run the command, or add the block to ~/.codex/config.toml.

    terminal
    codex mcp add klio --url https://klio.dev/api/mcp --bearer-token-env-var KLIO_TOKEN
  3. Or edit the config

    ~/.codex/config.toml
    [mcp_servers.klio]
    url = "https://klio.dev/api/mcp"
    bearer_token_env_var = "KLIO_TOKEN"
  4. Check it works

    Run codex, then /mcp. Klio's tools are listed. Ask: “call klio whoami”. For a full check, paste the verification prompt: it runs the whole loop on a sandbox story and gives Codex a badge.

Keep Codex on Klio for every request

Add this to AGENTS.md in your repo. Codex reads it on every turn, so follow-up work mid-session lands on the board too, not only in its own todo list.

AGENTS.md
## Klio (project board)
This repo is tracked in Klio; the Klio MCP server is connected.
- All coding work here goes through Klio, follow-ups mid-session included. Before writing code for anything I ask that has no ID, add it: `create_issue` (or `create_feature` for a bigger piece), then `start_issue`. Use your own todo list only for steps inside a Klio story.
- When I mention an ID like POC-F4 or POC-33, load it with `get_feature` / `get_issue` first. If I just say "continue", call `get_next_work`.
- `start_issue` before you start, `check_criterion` as each acceptance criterion passes, `complete_issue` with a short summary when done (`startNext: true` claims the next story; `prUrl` links the pull request if you opened one).
- Record new dependencies and providers with `sync_stack` / `add_service`. Never print or commit secret values.

Then paste the setup prompt

With Codex connected, this puts the repo on your board and starts building with you. Replace the highlighted part.

The setup prompt
Use Klio (klio.dev) as the project board for this repo. It's connected over MCP as "klio".

1. Call whoami to check the connection. If it fails, stop and tell me what to fix.
2. Find this repo's project with list_projects. If there isn't one, create it with create_project: name it after the repo and pick a short key.
3. Record what's already here: call sync_stack with package.json (and any other manifests) and gitRemote (the output of `git remote -v`), add features that already work as done stories, and half-finished work as stories in progress.
4. What I'm building next: <describe it in a sentence or two>
   Call brief_feature, write small stories with acceptance criteria, show me the plan, and save it with create_feature once I approve.
5. Build it one story at a time: start_issue before you write code, check_criterion as each criterion really passes, complete_issue with a short summary once it's tested. Don't start a second story while one is in progress, and leave Done to me.
6. Before you stop, hand me anything only I can do (secrets, DNS, billing) with flag_for_human.

Working with Codex day to day

  1. Plan in a sentence

    Tell Codex what you want: “add password reset by email”. It reads the project with brief_feature, proposes small stories with acceptance criteria, and saves them with create_feature once you agree.

  2. Say “continue”

    get_next_work returns the next story (reserved for Codex), the project's note and what other agents changed. start_issue claims it.

  3. Build to the criteria

    Codex ticks each criterion with check_criterion as it really passes, and hands you anything only you can do (keys, DNS, billing) with flag_for_human.

  4. Review and come back any time

    complete_issue sends the story to review with a summary and rewrites the project's note. You mark it done. Next week, “continue” starts right there.

Questions

Does Codex work with Klio?

Yes. Klio is an MCP server at https://klio.dev/api/mcp. Codex with MCP sign-in connects with the URL alone and you approve it in the browser; any version can connect with a token from Settings → Connect agents.

How do I make Codex use Klio for every request?

Add the short Klio section above to AGENTS.md. It's read at the start of every session, so follow-up requests land on the board too, not only the first one.

Can Codex work on the same project as other agents?

Yes. Every agent connected to Klio sees the same board. Claims stop two agents taking the same story, dependencies keep the order, and each agent sees what the others changed since it last looked.

Is Klio free?

Klio is free for one person with three projects and two agent connections. Pro adds unlimited projects and agents; agents never count as seats.

Further reading

Other agents

Endpoint: https://klio.dev/api/mcp. Menus and file paths can move between Codex releases; if a step looks different, the server URL and header are what matter.