# How to use Nylas MCP with Cursor

Source: https://developer.nylas.com/docs/cookbook/ai/mcp/cursor/

[Cursor](https://cursor.com/) reads MCP servers from a JSON file, and it supports OAuth for remote servers. That means you can connect it to the Nylas MCP server without putting an API key anywhere: add the URL, sign in once in your browser, and Cursor's agent can read and draft email, check calendars, and look up contacts across Gmail, Outlook, and IMAP accounts.

## Before you begin


Before you start, make sure you have:

1. **A Nylas account.** Sign up at [dashboard.nylas.com](https://dashboard.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, if you don't sign in.** Go to API Keys > Create new key. If you [sign in with your Nylas account](/docs/dev-guide/mcp/#sign-in-or-use-an-api-key) instead, you don't need a 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 Cursor installed. The [Cursor MCP documentation](https://cursor.com/docs/context/mcp) covers its MCP settings in full.

## Choose where the config lives

Cursor reads MCP servers from 2 files, and both use the same JSON shape. Put the Nylas server in the global file to use it in every project, or in the project file to share it with a repository. The project file is checked into git with your code, so never put a literal API key there.

| File | Scope |
| --- | --- |
| `~/.cursor/mcp.json` | Every project on your machine |
| `.cursor/mcp.json` | One project, shared with anyone who clones it |

## Sign in with your Nylas account

Signing in is the simplest setup and keeps keys out of your files. Add the server URL with no headers. The first time Cursor connects, it opens the Nylas Dashboard in your browser, where you pick up to 5 connected accounts and choose **Read and write**, **Read only**, or custom permissions.

```json [cursorSetup-Sign in]
{
  "mcpServers": {
    "nylas": {
      "url": "https://mcp.us.nylas.com"
    }
  }
}
```

A sign-in token lasts 15 minutes and refreshes on its own until you disconnect. Your Dashboard role caps the access you can grant, and the 5 standalone Notetaker tools aren't available with a sign-in. To change the accounts or access, sign in again after you disconnect.

## Connect with an API key

Use an API key when Cursor runs unattended, or when you need the standalone Notetaker tools. Cursor interpolates `${env:NAME}` in `headers`, so the key can stay in your shell environment instead of the file. Cursor reads the variable from the environment it was started in, so launch it from a shell that has `NYLAS_API_KEY` set.

```json [cursorSetup-API key]
{
  "mcpServers": {
    "nylas": {
      "url": "https://mcp.us.nylas.com",
      "headers": {
        "Authorization": "Bearer ${env:NYLAS_API_KEY}"
      }
    }
  }
}
```

For anything beyond your own testing, use an [IAM API key](/docs/v3/auth/nylas-iam/#create-and-manage-iam-api-keys) bound to one grant with only the permissions you need, not your application key. An application key reaches every grant in the application.

## Check the connection

Cursor picks up the file when you save it. Find the Nylas server in Cursor's list of MCP servers and confirm it's enabled. If it shows an error, open the **Output** panel and select **MCP Logs** to see the error. A `401` means the key is wrong or expired. A `403` means an IAM key is missing a permission or the grant isn't in its binding.

Then ask the agent something that needs a tool call:

```text
List my 5 most recent unread emails and who they're from.
```

The agent calls `list_messages` with an unread filter and returns the senders and subjects. If you connected more than one account, name the email address so it picks the right grant.

## Example prompts for Cursor's agent

These prompts work well in Cursor because they turn email and calendar context into something you act on while coding. Each one maps to 1 or 2 MCP tools, and the server's 90-second timeout applies to every call.

- **Pull a bug report into context:** "Find the email from support@example.com about the checkout error and summarize the steps to reproduce." Uses `list_messages` and `get_message`.
- **Reply without leaving the editor:** "Draft a reply to that email saying the fix ships Thursday." Uses `create_draft`. Nothing sends until you review it.
- **Plan around meetings:** "What meetings do I have this afternoon?" Uses `list_calendars` and `list_events`.
- **Book a review:** "Find 30 minutes tomorrow when alex@example.com and I are both free." Uses `availability`.

## Things to know about Cursor and Nylas MCP

- **Sending takes 2 steps.** The server requires `confirm_send_message` or `confirm_send_draft` before `send_message` or `send_draft`. Leave tool approval on for these tools so you see the message before it goes out.
- **Large mailboxes fill context fast.** Email bodies are long. Ask for a date range, a folder, or a search term instead of "all my email".
- **EU applications use a different URL.** Replace the URL with `https://mcp.eu.nylas.com`. A sign-in only includes grants in that region.
- **Project files are shared.** `.cursor/mcp.json` with `${env:NYLAS_API_KEY}` is safe to commit, because each developer supplies their own key. The sign-in config is safe to commit too.
- **Email content is untrusted input.** A message can contain instructions aimed at your agent. Keep tool approvals on for send and delete tools.

## 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 |
| `download_attachment` | Download an email message attachment with a maximum size of 10 MiB |
| `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_notetaker_transcript` | Download the transcript content for one grant-scoped Notetaker bot, up to 10 MiB |
| `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.

If you connect by signing in, the 5 standalone Notetaker tools aren't available. For full tool documentation, see the [Nylas MCP reference](/docs/dev-guide/mcp/).


## What's next

- [Nylas MCP server](/docs/dev-guide/mcp/) for setup in other clients and the full security guidance
- [Nylas IAM](/docs/v3/auth/nylas-iam/) to create a scoped API key for an agent
- [Use Nylas MCP with Claude Code](/docs/cookbook/ai/mcp/claude-code/) for the terminal setup
- [Use Nylas MCP with Codex CLI](/docs/cookbook/ai/mcp/codex-cli/) for OpenAI's coding agent
- [Give an AI agent read-only email access](/docs/cookbook/ai/mcp/read-only-email-agent/) to limit what the agent can do