How to use Nylas MCP with Codex CLI

Copy as MarkdownCurl Markdown

Open in

Codex CLI is OpenAI’s AI coding agent for the terminal. It connects to MCP servers through a config.toml file, which makes adding the Nylas MCP server a matter of adding a few lines of TOML. Once connected, Codex can search your inbox, check your schedule, draft messages, and create events across Gmail, Outlook, Exchange, and any IMAP provider.

The Nylas MCP server uses streamable HTTP with Bearer token authentication. Codex handles this natively through its bearer_token_env_var config option, so there is no need for proxy wrappers or OAuth flows.

Why connect Codex to Nylas?

Without MCP, working with email or calendar data during a coding session means switching to a browser, finding the information you need, and pasting it back. Connecting Codex to Nylas through MCP removes that context-switching overhead:

• Access real email and calendar data inline. Ask Codex to look up messages, check availability, or find contacts without leaving your terminal.
• Multi-provider coverage. One connection covers Gmail, Outlook, Yahoo, iCloud, Exchange, and any IMAP server.
• Safe email sending. The MCP server requires a two-step confirmation before sending any message, preventing accidental sends from misinterpreted prompts.
• Shared config between CLI and IDE. MCP servers in ~/.codex/config.toml work in both the terminal and the VS Code extension, so you set this up once.

Before you begin

Before you start, make sure you have:

1. A Nylas account. Sign up at dashboard-v3.nylas.com if you don’t have one.
2. A Nylas application. Go to All apps > Create new app > Choose your region (US or EU).
3. An API key. Go to API Keys > Create new key.
4. At least one connected grant. Go to Grants > Add Account and authenticate an email account (Gmail, Outlook, etc.).

New to Nylas? The Getting started guide walks through account setup, application creation, and connecting your first grant in detail.

You also need Codex CLI installed. If you haven’t set it up yet, follow the Codex CLI quickstart.

Set up the Nylas MCP server

Codex stores MCP server configuration in config.toml. You can configure it globally (~/.codex/config.toml) or per-project (.codex/config.toml in a trusted project directory).

Option 1: Add to global config

Edit ~/.codex/config.toml and add the Nylas MCP server:

config.toml (global)

[mcp_servers.nylas]
url = "https://mcp.us.nylas.com"
bearer_token_env_var = "NYLAS_API_KEY"

This tells Codex to read your API key from the NYLAS_API_KEY environment variable and pass it as a Bearer token. Set the variable in your shell profile:

Shell profile

# Add to ~/.zshrc, ~/.bashrc, or equivalent
export NYLAS_API_KEY="nyl_v0_your_key_here"

If your Nylas application is in the EU region, use https://mcp.eu.nylas.com instead.

Option 2: Add to project config

For project-scoped configuration, create .codex/config.toml in your project root:

config.toml (project)

[mcp_servers.nylas]
url = "https://mcp.us.nylas.com"
bearer_token_env_var = "NYLAS_API_KEY"

Project-scoped MCP servers only work in trusted projects. Codex will prompt you to trust the project directory the first time you run it.

Do not put your API key directly in config.toml. Use bearer_token_env_var to reference an environment variable. This keeps your credentials out of version control.

Advanced configuration options

Codex supports additional options for fine-tuning MCP server behavior:

config.toml (advanced)

[mcp_servers.nylas]
url = "https://mcp.us.nylas.com"
bearer_token_env_var = "NYLAS_API_KEY"
startup_timeout_sec = 10
tool_timeout_sec = 90
enabled = true

Option	Default	Description
startup_timeout_sec	10	How long to wait for the MCP server to respond on first connection
tool_timeout_sec	60	Maximum time for individual tool calls
enabled	true	Set to false to temporarily disable without removing the config

Verify the connection

Start a new Codex session and check that the Nylas tools are available:

CLI

codex

Once inside Codex, ask it to list your connected accounts:

List my connected email accounts using the Nylas MCP tools

If the connection is working, Codex will call the get_grant tool and return your grant details. If you see an error about the MCP server not being found, double-check that NYLAS_API_KEY is set in your current shell session.

Example workflows

Once connected, Codex translates your natural language requests into MCP tool calls. Here are practical examples you can try immediately.

Triage your inbox

Show me unread emails from the last 24 hours and group them by sender

Codex calls get_grant to resolve your account, then list_messages with date and unread filters. It groups messages by sender and surfaces anything that looks urgent. This works well for morning standup prep or catching up after being heads-down on code.

Check your schedule

What meetings do I have this week? Show me any days with back-to-back meetings.

Codex uses list_calendars and list_events with a date range, then identifies scheduling patterns like consecutive meetings with no buffer. This works across Google Calendar, Outlook, and any connected calendar provider.

Draft a reply

Draft a reply to the most recent email from the engineering team saying I'll have the PR ready by end of day

Codex finds the relevant message with list_messages, then calls create_draft with the original thread ID so the reply stays in the same conversation. The draft lands in your email client for review. Nothing is sent until you explicitly approve it.

Check availability and schedule

Check if both [email protected] and [email protected] are free tomorrow at 3pm, then create a 45-minute meeting called "Sprint Planning"

Codex calls availability first. If the slot is open, it calls create_event with the title, participants, and duration. If there’s a conflict, Codex tells you and can suggest alternative times.

Search across accounts

If you have multiple grants connected (work and personal email):

Search my work email for messages about "deployment pipeline" from the last week

Codex resolves the right grant using get_grant with your work email address, then runs list_messages with a search query filter. You can also ask Codex to search all connected accounts if you’re not sure where a conversation lives.

Things to know about Codex CLI and Nylas MCP

• Send confirmations are enforced. The Nylas MCP server requires a two-step flow for sending email: call confirm_send_message first to get a confirmation hash, then pass it to send_message. This prevents accidental sends from prompt injection or misinterpreted instructions. Codex handles the two-step flow automatically, but you’ll see the confirmation step in the tool call output.

• Tool timeouts default to 60 seconds. Codex’s default tool_timeout_sec is 60 seconds, but the Nylas MCP server allows up to 90 seconds. If you’re querying large mailboxes or wide date ranges and hitting timeouts, increase tool_timeout_sec to 90 in your config.

• Grant discovery is per-request. The MCP server doesn’t cache grant lookups between sessions. Codex (or you) need to provide an email address, and the server resolves it to a grant ID using get_grant. If you always use the same account, you can tell Codex your email upfront to save a round trip.

• The CLI and IDE extension share config. If you also use Codex in VS Code or another IDE, MCP servers configured in ~/.codex/config.toml are available in both. You only need to set this up once.

• EU region requires a different URL. If your Nylas application is in the EU region, use https://mcp.eu.nylas.com. The tools and behavior are identical.

• Use filters to stay within token limits. Listing hundreds of messages or events at once consumes a lot of context. Always use date range, folder, or search filters to keep responses focused and avoid truncation.

Available tools

The Nylas MCP server exposes these tools to your AI agent:

Tool	Description
list_messages	List and search email messages with filters (folder, date range, search query)
send_message	Send an email (requires confirm_send_message first)
create_draft	Create a draft email for review before sending
update_draft	Update an existing draft
send_draft	Send a previously created draft (requires confirm_send_draft first)
list_threads	List and search email threads
get_folder_by_id	Get folder details by ID
list_calendars	List all calendars for a connected account
list_events	List calendar events with date range and calendar filters
create_event	Create a new calendar event
update_event	Update an existing event
availability	Check free/busy availability for participants
get_grant	Look up a grant by email address
current_time	Get the current time in epoch and ISO 8601 format
epoch_to_datetime	Convert epoch timestamps to human-readable dates

The confirm_send_message and confirm_send_draft tools are safety gates that generate a confirmation hash before sending. Your AI agent must call the confirmation tool first, then pass the hash to the send tool. This prevents accidental sends from prompt injection or misinterpreted instructions.

For full tool documentation, see the Nylas MCP reference.

What’s next

• Nylas MCP reference for full MCP server documentation, client setup for other tools, and example conversations
• Email API reference for endpoint documentation for messages
• Calendar API reference for endpoint documentation for events
• Authentication overview to learn how grants and OAuth work
• Webhooks for real-time notifications when email or calendar data changes
• Use Nylas MCP with Claude Code for the same setup with Anthropic’s Claude Code
• Codex CLI documentation for the full guide to Codex CLI and MCP configuration
• Build an email agent with Nylas CLI for a step-by-step CLI walkthrough of building AI email agents
• Set up Nylas MCP from the CLI to install and configure the Nylas MCP server using the Nylas CLI