How to connect nicemails to Codex

Q: codex mcp login fails or the browser shows an error.

Check that url is exactly https://nicemails.net/mcp. nicemails registers clients automatically and does not use client ID metadata documents, so log in with --oauth-client-registration dcr. Do not set an OAuth client ID for nicemails: per the Codex docs, a configured client ID skips registration.

To give Codex an email inbox, add the nicemails MCP server with codex mcp add and its address, then run codex mcp login nicemails and approve access in your browser. The Codex CLI, the IDE extension and the ChatGPT desktop app share this configuration, so each of them can then use your mailboxes.

What do you need before you start?

A nicemails account with a mailbox for Codex to use. Sign-up is free and uses a code sent to your email instead of a password.
The Codex CLI or the Codex IDE extension. Per the Codex docs, MCP servers live in ~/.codex/config.toml, and a trusted project can add its own .codex/config.toml.

How do I add nicemails to Codex?

Add nicemails as a Streamable HTTP server:

codex mcp add nicemails --url https://nicemails.net/mcp

Adding a server does not sign you in. Start the OAuth sign-in separately, with automatic client registration:
```
codex mcp login nicemails --oauth-client-registration dcr
```
Your browser opens nicemails. Sign in with the code sent to your email, choose the permissions and whether Codex may use every mailbox or only one, then select Allow.
Start Codex, type /mcp to see nicemails among your active servers, and ask “list my nicemails mailboxes”.

On a machine without a browser, add --no-browser to the login command. Codex prints an authorization URL: open it on another device, sign in, then paste the full redirect URL back into the terminal, even if that page does not load.

You can also add the server by hand in ~/.codex/config.toml and then run the same login command:

[mcp_servers.nicemails]
url = "https://nicemails.net/mcp"

In the Codex IDE extension, open the gear menu, select MCP servers, then Add server. Choose Streamable HTTP, enter nicemails and the address, save, and select Restart extension. The extension shares its configuration with the CLI, so a server added in one shows up in the other.

How do I use an API key instead?

A key suits unattended runs where nobody can sign in. Create it first:

In nicemails, open Settings → API keys and select Create API key.
Choose AI agent (MCP) as the key purpose.
Pick the permissions and, if you like, limit the key to one mailbox.
Copy the key. It is shown only once.

Codex can read a bearer token from an environment variable, so the key never sits in config.toml. Set NICEMAILS_API_KEY, then use:

[mcp_servers.nicemails]
url = "https://nicemails.net/mcp"
bearer_token_env_var = "NICEMAILS_API_KEY"

What can Codex do with your mailboxes?

Codex gets the nicemails tools your permissions allow. There are 8:

list_mailboxes lists the mailboxes the connection can use.
list_messages lists one folder of a mailbox, newest first.
search searches every folder of the selected mailboxes, including Spam.
get_message reads one message without marking it as read.
create_mailbox creates a new mailbox (Manage permission, account-wide connection).
move moves a message to another folder; flag marks it read, unread, starred or answered.
send_message sends from one of your mailboxes (Send permission; new recipients need your approval).

To keep Codex to reading, list only the read tools in enabled_tools:

[mcp_servers.nicemails]
url = "https://nicemails.net/mcp"
enabled_tools = ["list_mailboxes", "list_messages", "search", "get_message"]

A typical request: “Run the sign-up test, then search the qa mailbox for the welcome email and check that its links use the staging domain.”

Who approves what Codex does?

Codex decides when to ask you with default_tools_approval_mode. The writes mode asks only for tools that are not marked read-only, and nicemails marks list_mailboxes, list_messages, search and get_message as read-only, so Codex reads freely and asks before it creates, moves, flags or sends:

[mcp_servers.nicemails]
url = "https://nicemails.net/mcp"
default_tools_approval_mode = "writes"

Permissions: the connection gets only what you choose: Read (list, search and read mail), Manage (create mailboxes, move messages, set flags) and Send. A connection can also be limited to one mailbox.
Send approval: if a recipient is not someone you emailed from the web app, or trusted at an earlier approval, within the last 30 days, nothing is sent until you approve that message on a nicemails confirmation page while signed in. An unapproved request expires after 15 minutes.
Untrusted content: tool results mark email content as untrusted, and nothing inside an email can approve a send.
An off switch: disconnect Codex under Settings → API keys → Connected apps, or revoke its key. Access ends immediately.

Troubleshooting

codex mcp login fails or the browser shows an error.

Check that url is exactly https://nicemails.net/mcp. nicemails registers clients automatically and does not use client ID metadata documents, so log in with --oauth-client-registration dcr. Do not set an OAuth client ID for nicemails: per the Codex docs, a configured client ID skips registration.

Codex times out while starting nicemails.

Codex waits 10 seconds for a server to start by default. On a slow network, raise it with startup_timeout_sec = 20 in the [mcp_servers.nicemails] table.

Does the IDE extension need its own setup?

No. The CLI, the IDE extension and the ChatGPT desktop app share the same configuration. After you change it, select Restart extension in the IDE.

Related guides

Start for free