Before: giving an AI assistant email access meant writing wrapper functions, defining tool schemas by hand, managing OAuth tokens, and re-doing all of it for every agent runtime you supported. After: one install command registers a full set of email, calendar, and contacts tools in whatever MCP host you're running, and the agent can optionally own the mailbox outright.
That's the shift MCP (Model Context Protocol) brought to agent tooling, and email is one of the clearest places to see it.
If your agent runs in an MCP-capable host — Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, or the OpenAI Codex CLI — the Nylas CLI registers itself as an MCP server:
nylas mcp install --assistant claude-code
nylas mcp install --assistant cursor
nylas mcp install --all # installs for all detected assistants
Verify with nylas mcp status
. That's the whole integration: your agent now has 16 email, calendar, and contacts tools available natively, with no subprocess calls and no tool schemas to write. The autonomous agents quickstart walks through the setup from a bare machine, and it's written to be followed by the agent itself — the only step that needs a human is nylas init
, which opens a browser once for sign-in.
Behind the MCP server sits a unified API, so the same tools work whether the connected account is Gmail, Microsoft 365, Yahoo, iCloud, IMAP, or Exchange. The agent doesn't know or care which provider it's talking to.
Here's the design question MCP doesn't answer for you: when your agent reads and sends mail, whose mail is it? There are two patterns, and the docs are explicit about when each fits.
Share a human's inbox. The agent operates on an account that belongs to a person — their Gmail, their calendar. Replies go to the human. Right choice when the agent is a personal assistant.
Give the agent its own inbox. The agent gets a dedicated mailbox at its own address — hosted, API-driven, no OAuth at all. Right choice when the agent is the identity: a sales agent, a scheduling bot, a service mailbox. This runs on Agent Accounts, currently in beta:
nylas agent account create agent@yourdomain.com
Both patterns use the same grant model, so you can mix them — one agent triaging a shared support@
inbox while sending outreach from its own address. And because an Agent Account is just another grant, the MCP tools, the CLI commands, and every API endpoint work identically against it. Switch the active grant and your whole MCP toolset is now operating the agent's own mailbox.
Tools are half the integration; the other half is the agent knowing how to use them. A few things in the stack are built specifically for machine consumption:
npx skills add nylas/skills
pre-loads your coding agent with current API and CLI context — commands, flags, output shapes — so it runs things correctly on the first try. Works with Claude Code, Cursor, Codex CLI, and 40+ other agents. In Claude Code it's a plugin: /plugin marketplace add nylas/skills
.llms.txt
is a curated sitemap; llms-full.txt
is every page in one file for big context windows; and any docs URL returns clean markdown if you send Accept: text/markdown
(the response includes an x-markdown-tokens
header with the estimated token count).
curl https://developer.nylas.com/llms.txt
curl -H "Accept: text/markdown" https://developer.nylas.com/docs/v3/email/
So when the agent needs an API detail the MCP tools don't expose, it can fetch exactly the page it needs without scraping HTML.
MCP tools are pull-based: the agent acts when prompted. For an agent that reacts — replying to inbound mail, processing meeting changes — you add a push channel:
nylas webhook create \
--url https://youragent.example.com/webhooks/nylas \
--triggers "message.created,message.updated"
Webhooks fire for connected grants and Agent Accounts alike, so the architecture is: webhook wakes the agent up, MCP tools (or CLI commands) let it act.
Not every runtime does, and the fallback is graceful: the same CLI that backs the MCP server works as plain subprocess calls. The LLM agent with tools recipe wraps nylas email list
, nylas email send
, and the calendar commands as Python functions and plugs them into a standard tool-calling loop — under 50 lines, versus roughly 300 lines of token plumbing for hand-rolled Gmail OAuth alone (600 with Microsoft Graph, past 1,000 with IMAP fallback).
Three flags carry the subprocess route, and they're the same rules the docs give autonomous agents directly:
--json
--yes
--limit
--limit 100
floods the context window.One more rule from the same list: don't hardcode grant IDs. Run nylas auth whoami --json
to discover the active grant at runtime, or set the NYLAS_GRANT_ID
environment variable.
Errors come back in a consistent JSON envelope, which matters more for agents than for humans — the model can branch on a field instead of parsing prose:
{
"request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
"error": {
"type": "unauthorized",
"message": "Unauthorized"
}
}
The common error.type
values map to clear recoveries: unauthorized
means a bad or expired key (mint a new one with nylas dashboard apps apikeys create
), not_found_error
means an invalid grant (reconnect with nylas auth login
), and rate_limit_error
means back off and retry. An MCP-connected agent that knows these three cases can self-heal most failures without escalating to a human.
A complete MCP email setup ends up being four layers, each one command or one file:
nylas init
— credentials (the one human step)nylas mcp install --assistant <host>
— 16 tools registerednylas agent account create ...
— optional agent-owned identitynylas webhook create ...
— optional real-time triggersCompare that with the before picture: per-provider OAuth implementations, hand-written schemas, and a different integration per runtime. The coding agents guide covers the SDK route if you're building a SaaS product rather than wiring up an assistant — same grant model, different entry point.
If you've already got an MCP host running, the experiment costs five minutes: install the server, ask your agent to list its unread mail, then ask it to draft a reply. Which host are you running — and what's the first email task you'd hand off?