# How to use Nylas MCP with Codex CLI

Source: https://developer.nylas.com/docs/cookbook/ai/mcp/codex-cli/

[Codex CLI](https://developers.openai.com/codex/) 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](/docs/provider-guides/google/), [Outlook](/docs/provider-guides/microsoft/), [Exchange](/docs/provider-guides/imap/), 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](/docs/provider-guides/google/), [Outlook](/docs/provider-guides/microsoft/), [Yahoo](/docs/provider-guides/yahoo-authentication/), [iCloud](/docs/provider-guides/icloud/), [Exchange](/docs/provider-guides/imap/), 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](https://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.).

> **Info:** 
> **New to Nylas?** The [Getting started guide](/docs/v3/getting-started/) 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](https://developers.openai.com/codex/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:

```toml [codexSetup-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:

```bash [codexSetup-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:

```toml [codexSetup-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.

> **Warn:** 
> **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:

```toml [codexSetup-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:

```bash
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 alex@example.com and jamie@example.com 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 |
|---|---|
| `availability` | Find available meeting times across one or more Nylas grants |
| `confirm_send_draft` | Generate the confirmation hash required before calling `send_draft` |
| `confirm_send_message` | Generate the confirmation hash required before calling `send_message` |
| `create_draft` | Create a draft email using only the fields the user provided |
| `create_event` | Create a calendar event |
| `current_time` | Get the current epoch time and ISO 8601 date for a timezone |
| `datetime_to_epoch` | Convert a date, time, and timezone to a Unix timestamp |
| `delete_draft` | Delete a draft email |
| `delete_event` | Delete a calendar event |
| `epoch_to_datetime` | Convert Unix timestamps to human-readable date and time values |
| `get_contact` | Get a single contact by ID |
| `get_event` | Get a single event by ID |
| `get_folder_by_id` | Get folder or label details by ID |
| `get_grant` | Look up a grant by email address |
| `get_message` | Get a single email message by ID, including full body content |
| `get_notetaker` | Get details for one grant-scoped Notetaker bot |
| `get_notetaker_media` | Get fresh media links for one grant-scoped Notetaker bot |
| `get_search_syntax` | Get provider-specific native search syntax for messages and threads |
| `get_standalone_notetaker` | Get details for one standalone Notetaker bot |
| `get_standalone_notetaker_media` | Get fresh media links for one standalone Notetaker bot |
| `list_calendars` | List all calendars for a connected account |
| `list_contacts` | List contacts, with optional filters for email, phone number, source, or group |
| `list_events` | List events in a calendar |
| `list_folders` | List email folders or labels |
| `list_messages` | List and search email messages |
| `list_notetakers` | List grant-scoped Notetaker bots |
| `list_standalone_notetakers` | List standalone Notetaker bots for the application |
| `list_threads` | List and search email threads |
| `schedule_notetaker` | Schedule a grant-scoped Notetaker bot for a future meeting |
| `schedule_standalone_notetaker` | Schedule a standalone Notetaker bot for a future meeting |
| `send_draft` | Send a previously created draft |
| `send_message` | Send an email directly |
| `send_notetaker` | Send a grant-scoped Notetaker bot to an active meeting |
| `send_standalone_notetaker` | Send a standalone Notetaker bot to an active meeting |
| `update_draft` | Update an existing draft |
| `update_event` | Update an existing event |

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. The `delete_draft` and `delete_event` tools are irreversible, so confirm with the user before calling them.

For full tool documentation, see the [Nylas MCP reference](/docs/dev-guide/mcp/).


## What's next

- [Nylas MCP reference](/docs/dev-guide/mcp/) for full MCP server documentation, client setup for other tools, and example conversations
- [Email API reference](/docs/api/v3/ecc/#tag--Messages) for endpoint documentation for messages
- [Calendar API reference](/docs/api/v3/ecc/#tag--Events) for endpoint documentation for events
- [Authentication overview](/docs/v3/auth/) to learn how grants and OAuth work
- [Webhooks](/docs/v3/notifications/) for real-time notifications when email or calendar data changes
- [Use Nylas MCP with Claude Code](/docs/cookbook/ai/mcp/claude-code/) for the same setup with Anthropic's Claude Code
- [Codex CLI documentation](https://developers.openai.com/codex/) for the full guide to Codex CLI and MCP configuration
- [Build an email agent with Nylas CLI](https://cli.nylas.com/guides/build-email-agent-cli) for a step-by-step CLI walkthrough of building AI email agents
- [Set up Nylas MCP from the CLI](https://cli.nylas.com/guides/ai-agent-email-mcp) to install and configure the Nylas MCP server using the Nylas CLI