DEV Community

Qasim Muhammad
Qasim Muhammad

Posted on

MCP and Email: Wiring an Agent Account Into Your AI Stack

#mcp #ai #email #agents

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.

The one-command integration

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
Enter fullscreen mode Exit fullscreen mode

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.

Whose mailbox is it, though?

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
Enter fullscreen mode Exit fullscreen mode

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.

Context, not just tools

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:

  • Skills. 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.
  • Agent-readable docs. 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/
Enter fullscreen mode Exit fullscreen mode

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.

Where webhooks fit

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"
Enter fullscreen mode Exit fullscreen mode

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.

If your host doesn't speak MCP

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 on everything — without it the CLI prints human-formatted text the model has to guess at.
  • --yes on sends and deletes — without it the command blocks on a confirmation prompt no agent will ever answer.
  • --limit on list commands — start with 5; --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.

When a tool call fails

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"
  }
}
Enter fullscreen mode Exit fullscreen mode

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.

The stack, assembled

A complete MCP email setup ends up being four layers, each one command or one file:

  1. nylas init — credentials (the one human step)
  2. nylas mcp install --assistant <host> — 16 tools registered
  3. nylas agent account create ... — optional agent-owned identity
  4. nylas webhook create ... — optional real-time triggers

Compare 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?

Top comments (0)