Skip to content
Skip to main content

How to use Nylas MCP with Cursor

Last updated:

Cursor 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 start, make sure you have:

  1. A Nylas account. Sign up at 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 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.).

You also need Cursor installed. The Cursor MCP documentation covers its MCP settings in full.

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.

FileScope
~/.cursor/mcp.jsonEvery project on your machine
.cursor/mcp.jsonOne project, shared with anyone who clones it

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.

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.

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.

For anything beyond your own testing, use an IAM API key bound to one grant with only the permissions you need, not your application key. An application key reaches every grant in the application.

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:

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.

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 [email protected] 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 [email protected] and I are both free.” Uses availability.
  • 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.

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

ToolDescription
availabilityFind available meeting times across one or more Nylas grants
confirm_send_draftGenerate the confirmation hash required before calling send_draft
confirm_send_messageGenerate the confirmation hash required before calling send_message
create_draftCreate a draft email using only the fields the user provided
create_eventCreate a calendar event
current_timeGet the current epoch time and ISO 8601 date for a timezone
datetime_to_epochConvert a date, time, and timezone to a Unix timestamp
delete_draftDelete a draft email
delete_eventDelete a calendar event
download_attachmentDownload an email message attachment with a maximum size of 10 MiB
epoch_to_datetimeConvert Unix timestamps to human-readable date and time values
get_contactGet a single contact by ID
get_eventGet a single event by ID
get_folder_by_idGet folder or label details by ID
get_grantLook up a grant by email address
get_messageGet a single email message by ID, including full body content
get_notetakerGet details for one grant-scoped Notetaker bot
get_notetaker_mediaGet fresh media links for one grant-scoped Notetaker bot
get_notetaker_transcriptDownload the transcript content for one grant-scoped Notetaker bot, up to 10 MiB
get_search_syntaxGet provider-specific native search syntax for messages and threads
get_standalone_notetakerGet details for one standalone Notetaker bot
get_standalone_notetaker_mediaGet fresh media links for one standalone Notetaker bot
list_calendarsList all calendars for a connected account
list_contactsList contacts, with optional filters for email, phone number, source, or group
list_eventsList events in a calendar
list_foldersList email folders or labels
list_messagesList and search email messages
list_notetakersList grant-scoped Notetaker bots
list_standalone_notetakersList standalone Notetaker bots for the application
list_threadsList and search email threads
schedule_notetakerSchedule a grant-scoped Notetaker bot for a future meeting
schedule_standalone_notetakerSchedule a standalone Notetaker bot for a future meeting
send_draftSend a previously created draft
send_messageSend an email directly
send_notetakerSend a grant-scoped Notetaker bot to an active meeting
send_standalone_notetakerSend a standalone Notetaker bot to an active meeting
update_draftUpdate an existing draft
update_eventUpdate 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.