How do Codex notifications work?
Codex connects to Notifex as a remote MCP server over HTTP. When Codex needs a decision, it calls ask_question, your phone gets a push, and Codex waits. You tap an option or type a reply, and Codex continues with your answer. For a plain update, such as "tests pass", it sends a one-way message instead.
Before you start
- Install Notifex on your iPhone or Android phone, sign in and allow notifications.
- Create a project. Copy the secret key: it is shown once.
How do I add Notifex to Codex?
Codex reads MCP servers from ~/.codex/config.toml. Add a Notifex table that points at the hosted endpoint and names an environment variable for your key:
[mcp_servers.notifex]
url = "https://mcp.notifexapp.com/mcp"
bearer_token_env_var = "NOTIFEX_API_KEY"
tool_timeout_sec = 3600tool_timeout_sec matters. Codex stops waiting on a tool call after 60 seconds by default, and ask_question waits until you answer. The line above gives you an hour. If you may take longer, tell Codex to ask with wait=false and check back with check_answer. Either way, the question stays open in your inbox.
Then set the variable in the shell you start Codex from, with your key in place of the placeholder:
export NOTIFEX_API_KEY="<YOUR_API_KEY>"To limit Notifex to one project, put the same table in .codex/config.toml inside a trusted project. Run codex mcp list, or type /mcp in Codex, to check that notifex is there. Codex then sees the seven Notifex tools: create_thread, send_message, ask_question, ask_questions, wait_for_answer, check_answer and create_upload.
Can Codex send a notification when it is done?
Yes. Tell Codex to send you a Notifex message when it finishes. Put the rule in your project's AGENTS.md so Codex follows it in every session:
## Notifex
- Before you deploy, delete data or pick between options I have not decided, ask me with Notifex (ask_question) and wait for my answer.
- When you finish, send me one Notifex message (send_message) with a one-line summary of what changed.
- Start a new Notifex thread (create_thread) for each new topic.
Tips for long runs
- One thread per topic. create_thread starts a thread, and its subject is the push title.
- Batch related questions. ask_questions sends up to 10 in one push.
- Show, do not describe. create_upload attaches screenshots, logs or video, up to 10 files of 10 MB each.
- Share the team. In a team project every member gets the push, and the first answer wins.
The endpoint, keys and tool limits are in Connect your agent.
Questions about Notifex and Codex
Yes, as long as tool_timeout_sec allows it. Codex stops waiting on a tool after 60 seconds by default, so the config above raises it to one hour. For longer waits, Codex can ask with wait=false and check back with check_answer.
In an environment variable. config.toml names the variable with bearer_token_env_var, so the key itself stays out of the file.
Yes. Ask Codex to send you a Notifex message with send_message when it finishes. It arrives as a push on your phone.
No. Notifex is free on the App Store and Google Play.
Get Notifex on your phone
Free on the App Store and Google Play. Then add one MCP entry and let your agent ask.

