How to connect Codex to Fastmail MCP

Fastmail now has an official MCP server, which means Codex can connect to your Fastmail account and work with your mail, calendar, and contacts through OAuth. Pretty handy, eh?

The short version: Fastmail’s MCP endpoint works (sort of), but Codex’s native OAuth registration path may currently fail because Fastmail expects a scope during dynamic client registration. A reliable workaround is to connect via mcp-remote.

Here me asking Fastmail (thru MCP) how many emails I’ve sent in the past 24 hours.

Here’s the setup.

Open your Codex config

Edit:

~/.codex/config.toml

Add or replace the Fastmail MCP entry with this:

[mcp_servers.fastmail]
startup_timeout_sec = 300
command = "npx"
args = [
    "-y",
    "mcp-remote@latest",
    "https://api.fastmail.com/mcp",
    "--transport",
    "http-only",
    "--resource",
    "https://api.fastmail.com/mcp",
    "--static-oauth-client-metadata",
    '{ "scope": "https://www.fastmail.com/dev/mcp offline_access" }',
    "--auth-timeout",
    "300",
]
enabled = true

Why this works

Fastmail’s official MCP server is:

https://api.fastmail.com/mcp

The important bit is this line:

'{ "scope": "https://www.fastmail.com/dev/mcp offline_access" }'

Fastmail requires OAuth scopes during registration. At the time of writing, codex mcp login fastmail --scopes ... can still fail with:

invalid_request no scope

Using mcp-remote lets us pass the scope at the correct stage of the OAuth flow.

Restart Codex

After saving the config, restart Codex so it reloads the MCP server list. Let it do its thing.

Do NOT run:

codex mcp login fastmail

That command is for native remote MCP OAuth. In this setup, mcp-remote handles the OAuth flow as a local stdio bridge.

mcp-remote is a small adapter for MCP clients that only know how to run local MCP servers over stdio, but you want them to talk to a remote MCP server over HTTP/SSE, including OAuth-style authentication.

Many popular MCP clients historically worked best with local stdio servers, while newer MCP servers may be hosted remotely and require OAuth/auth flows.

Think of it like a travel plug adapter:

• Codex expects: local command over stdio
• mcp-remote translates to: remote MCP server over HTTP/SSE

Authorise Fastmail

When Codex first tries to use the Fastmail MCP server, your browser should open a Fastmail authorisation page.

Fastmail will ask which access level you want to grant. Choose only what you’re comfortable with:

• Read access: search and read mail, contacts, and calendars
• Write access: draft replies, organise mail, update contacts and calendars
• Send access: send email on your behalf

Only set the level of access you’re comfortable with.

The config above gives the MCP connection enough OAuth permission to complete the flow, but Fastmail still lets you approve the practical access level during consent.

If the browser shows “localhost refused”

If you authorise Fastmail and land on a Chrome page saying:

localhost refused to connect

the callback listener probably timed out before the browser returned.

That’s why the config uses:

startup_timeout_sec = 300

and:

"--auth-timeout",
"300",

This gives you five minutes to finish the OAuth consent flow.

If it still happens, add debug logging:

"--debug",

inside the args list, then check:

~/.mcp-auth/

for the debug log.

Confirm Codex sees it

Run:

codex mcp get fastmail --json

You should see Fastmail configured as a stdio MCP server using npx mcp-remote.

That’s it. Codex should now be able to use Fastmail’s MCP tools once the OAuth flow completes.