Connect Soon to Codex

This adds Soon to Codex, the OpenAI command line agent.

Before you start

• A Soon account you can sign in to.
• The Codex CLI installed, and run from a normal terminal window.

You connect as yourself, so the assistant sees exactly what you see in Soon and nothing more. Your permissions carry over: if you cannot edit a board in Soon, the assistant cannot edit it either.

Run Codex from a terminal, not from the ChatGPT app

Codex also comes built into the ChatGPT desktop app. That version cannot complete the Soon sign-in: it runs in a protected sandbox with its own built-in browser, and the sign-in has to hand back to your normal browser to finish.

Use the standalone Codex CLI in Terminal or iTerm instead. If you are not sure which you have, run which codex. A path containing ChatGPT.app means you are on the built-in one.

To install the standalone version:

npm install -g @openai/codex

Steps

1. Open your Codex configuration file:

~/.codex/config.toml

1. Add these two lines at the end:

[mcp_servers.soon]

url = "https://mcp.soon.works/mcp"

1. Save the file and start Codex by running codex.
2. The first time you use a Soon command, a browser window opens with the Soon sign-in page. Sign in and select Approve.

Keep the terminal open while you complete the sign-in in your browser.

To confirm the entry is registered, run codex mcp list and look for Soon.

Check that it worked

Ask the assistant:

What is on my schedule this week?

You should get your own shifts back. If you are a planner, try "Who is working on Friday?" as well. If the assistant says it has no Soon tools available, the connection did not complete. See the troubleshooting section below.

What you can ask for

Once connected, you can ask in plain language. For example:

• "What am I working this week?"
• "Who is available to cover Friday evening?"
• "Request leave for the 12th to the 16th."
• "Move Jackson off Saturday and put Ada on instead."

Soon marks every action that changes the schedule as destructive, so your assistant asks before running one. That prompt comes from the assistant rather than from Soon, so only connect assistants you trust.

Turn it off

Remove the [mcp_servers.soon] section from your configuration file and restart Codex.

Troubleshooting

The browser says "localhost refused to connect"

This is the most common problem, and it is not a Soon error. The sign-in sends you back to a short lived address on your own machine, and that address only works while Codex is running.

First check you are not on the Codex built into the ChatGPT desktop app, which cannot complete this step at all. Run which codex: if the path contains ChatGPT.app, switch to the standalone CLI as described above. This is the single most common cause.

If you are already on the standalone CLI, start again and:

• Leave the terminal open and untouched while you sign in.
• Use only the link from the current attempt. The address changes every time, so an older link or tab points at nothing.
• Finish the browser step promptly rather than leaving it open.
• Run Codex on the same machine as your browser. If Codex runs on a remote server, the sign-in cannot reach back to it.

The sign-in gets stuck after a failed attempt

A half finished sign-in can leave stale credentials behind. Clear them and try again:

rm -rf ~/.mcp-auth

Codex cannot reach the server on startup

Check the address in your configuration file. If it points at a local or test address left over from earlier, replace it with the one above and restart Codex.

The assistant says it cannot see a board

The connection carries your own Soon permissions. If a board is missing, check in Soon that you have access to it. Ask your team owner to add you if not.

Still stuck

Contact us at support@soon.works and tell us which app you are connecting from. Include any error message you see.