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

  1. Install Notifex on your iPhone or Android phone, sign in and allow notifications.
  2. 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 = 3600

tool_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.
A Notifex thread on iPhone: the agent asks which build to prepare, with two options and a field to type an answer

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.

Get Notifex on your phone

Free on the App Store and Google Play. Then add one MCP entry and let your agent ask.

Download on the App StoreGet it on Google Play