Connect your inbox to OpenAI Codex
with one command
Give Codex a real mailbox. Read, search, draft, send, reply, forward, schedule and organize mail from the Codex CLI, the IDE extension or the ChatGPT desktop app, across every inbox you have connected.
Run codex mcp add mcpemails --url https://mcpemails.com/api/mcp. Codex detects that the server supports OAuth, opens the browser, and you approve access on the MCPEmails consent screen. The CLI, the IDE extension and the ChatGPT desktop app share the same config, so one setup covers all three.
How Codex connects: OAuth, no API key
Codex runs the standard MCP OAuth flow against this server. It registers itself, either with a client ID metadata document or with RFC 7591 dynamic client registration, so there is no client ID to create, and authorizes with authorization code plus PKCE using S256. No client secret is ever transmitted, and the token carries only the scopes you approve on our consent screen. The access token it receives lasts an hour and refreshes itself; it is listed in Dashboard, API Keys as OAuth: followed by the client name, which is where you revoke the connection.
The one value you need
Everything on this page is a way of getting this URL into OpenAI Codex.
| Field | Value |
|---|---|
| MCP server URL | https://mcpemails.com/api/mcp |
| Transport | Streamable HTTP (MCP 2025-06-18) |
| Authentication | OAuth 2.1, authorization code with PKCE. No API key. |
How to connect OpenAI Codex to your inbox
Four steps. The first two are the same for every client, the rest are specific to this one.
Create a free account and connect a mailbox
Sign up at mcpemails.com, no card required, then go to Dashboard, Inboxes, Connect Inbox. Outlook and Microsoft 365 connect with Sign in with Microsoft; Gmail, iCloud, Fastmail, Yahoo, Zoho and Yandex take an app-specific password; anything else connects over plain IMAP and SMTP. The free plan holds one inbox, forever.
Add the server from the CLI
Run the command below. It writes a [mcp_servers.mcpemails] entry with url to ~/.codex/config.toml, then prints Detected OAuth support. Starting OAuth flow… and opens your browser.
Or add it in the desktop app or IDE extension
In the ChatGPT desktop app, open Settings, then MCP servers; in the IDE extension, open the gear menu, then MCP servers. Select Add server, enter a name, choose Streamable HTTP, paste https://mcpemails.com/api/mcp, save, then select Restart (or Restart extension) and Authenticate.
Approve access
Sign in to MCPEmails in the browser, pick Read-only, Standard or Full access on the consent screen, and click Allow access. If the browser flow did not start, run codex mcp login mcpemails.
Check it and ask for something
Run codex mcp list, or /mcp inside a Codex session, to see the server. Then try "summarise anything unread from today". Codex calls inbox_list first to discover your mailboxes, so there are no ids to paste.
codex mcp add mcpemails --url https://mcpemails.com/api/mcpOfficial OpenAI Codex documentation for remote MCP servers: https://learn.chatgpt.com/docs/extend/mcp?surface=cli
Wondering which mailbox to connect first? See the provider compatibility matrix
What trips people up in Codex
Check which card the consent screen opens on
Codex asks for the scopes in our 401 challenge, which is read:email, so on some registrations the consent screen opens on Read-only. That is fine for triage. If you want Codex to draft or send, pick Standard or Full access before you click Allow. To widen it later, run codex mcp login mcpemails again and choose the wider card, or name the scopes with --scopes, for example --scopes read:email,search:email,manage:drafts.
The CLI, the IDE extension and the desktop app share one config
On the same machine, all three read the same ~/.codex/config.toml, so adding the server in one makes it appear in the others. A project can also carry its own .codex/config.toml, which Codex reads only for trusted projects. ChatGPT on the web does not read this file at all; for that, use the ChatGPT setup instead.
On a headless box, skip the local browser
On a server you reach over SSH, run codex mcp login mcpemails --no-browser: Codex prints the sign-in link, you open it on any machine, and paste back the address the browser lands on. In CI, create a scoped key in Dashboard, API Keys, export it, and set bearer_token_env_var on the server entry to that variable's name (or pass --bearer-token-env-var to codex mcp add). Codex then sends it in the Authorization header, and the key never sits in the config file.
Keep the default tool timeout
Codex waits 60 seconds for a tool call by default (tool_timeout_sec). That is enough even for bulk work: a move or delete across a large folder stops on the server's own time limit before then and returns a result marked partial, with the untouched messages listed in remaining_message_ids, so Codex can call again with those ids. Setting the timeout much lower can cut a call off before that result arrives.
Limits worth knowing
- Requests are rate limited to 100 per minute, 1,000 per hour and 10,000 per day per key, plus your plan ceiling on billable actions.
- The server is request and response only. There are no webhooks and no server-initiated events, so new mail never wakes your agent by itself. To react to arriving mail, poll on a schedule.
- Mail is fetched live from your provider on every call and never stored. Only the encrypted OAuth token or app password is kept, so a revoked token or a changed mailbox password ends access immediately.
OpenAI Codex and email, answered
How do I connect email to OpenAI Codex?
Run codex mcp add mcpemails --url https://mcpemails.com/api/mcp. Codex detects OAuth support, opens the browser, and you approve access on the MCPEmails consent screen. Codex then has tools for reading, searching, drafting, sending, replying, forwarding, organizing and scheduling mail.
What does the config.toml entry look like?
Two lines under ~/.codex/config.toml: a table named [mcp_servers.mcpemails] and url = "https://mcpemails.com/api/mcp". OAuth is the default for a server with a url, so nothing else is needed. If you write the entry by hand, run codex mcp login mcpemails to sign in.
Do I need an API key for Codex?
No. Codex signs in with OAuth, so nothing secret is typed into the config. A scoped key is there for machines without a browser: put it in an environment variable and point bearer_token_env_var at that variable.
Which mailboxes can Codex reach this way?
Outlook.com and Microsoft 365 over Sign in with Microsoft, where a work account may need an IT admin to approve the app once; Gmail, iCloud, Fastmail, Yahoo, Zoho and Yandex with an app-specific password; and any other mailbox that speaks IMAP and SMTP on the standard ports. The client sees them all through the same connection: your agent calls inbox_list first to discover every connected mailbox and its id, so there are no UUIDs to paste anywhere.
Can Codex send email without me seeing it?
Only if you let it. Sending is gated on the send:email scope, so a token without that scope cannot send at all. On top of that, an inbox owner can require human approval in the dashboard, which holds every send, reply, forward, draft send and scheduled send until a person releases it.
Is my email stored on your servers?
No. Every message is fetched live from your provider for the request that asked for it and handed straight to your client. Only the encrypted OAuth token or app password is kept, so future calls can authenticate. Deleting the inbox in the dashboard, or revoking access at your provider, ends the connection at once.
Give Codex a real inbox
One command, one browser sign-in. One inbox free forever, no card required.