Cursor·MCP server·4 min read

Mails.ai for Cursor — drop-in MCP server setup

MCP serveradd to ~/.cursor/mcp.json

Add to ~/.cursor/mcp.json under mcpServers, then restart Cursor.

{
  "mcpServers": {
    "mails": {
      "command": "npx",
      "args": ["-y", "@mailsai/mcp-server"],
      "env": {
        "MAILS_API_KEY": "mk_live_..."
      }
    }
  }
}

Cursor is an MCP-capable runtime. The mails.ai MCP server is the same npm-distributed process as the Claude Code setup — one JSON snippet in ~/.cursor/mcp.json, restart Cursor, and your in-IDE agent has email.

Why Cursor + mails.ai

Cursor’s in-IDE agent (Composer in Agent mode) is one of the most powerful environments for autonomous coding workflows. Adding email as an MCP tool means the agent can do things like:

Email a teammate when a draft branch is ready for review.
Send progress reports during long refactors.
Read a customer support thread (via mails.list_threads), draft a fix, and email back when shipped.
Process incoming bug reports as typed events — intent + entities + injection score — before deciding whether to act.

Cursor’s tool execution preview surfaces each mails.* call before execution, so you can review the recipient and body before the email actually goes out. Auto-approve the patterns you trust; keep confirmation on for high-stakes recipients.

Setup — three steps

Get an API key. Sign in at api.mails.ai/keys at Phase 1 launch, or request a closed-beta key from support@mails.ai.
Add the MCP server config. Open ~/.cursor/mcp.json in your editor and add the snippet from the install card above (replacing mk_live_... with your key). For project-scoped keys, use .cursor/mcp.json in the project root and add it to .gitignore.
Restart Cursor. The next session spawns the MCP server via npx on first tool invocation. Verify in Settings → MCP that mails appears in the registered servers list.

First commands to test

In Composer / Agent mode, prompt naturally:

# Verify the integration
> What mails.* tools are available to me?

# Send a test email (Cursor will preview the args before executing)
> Use mails.send to email me a hello from agent "test".

# Query recent inbound
> List the last day of threads on the test agent.

Cursor surfaces each tool call with its args before execution. Approve once to test; mark as “always allow” once you trust the pattern.

Common patterns

Branch-ready notification. Long-running coding agent finishes the work, calls mails.send to email reviewers with the diff link.
Review-cycle support. Background agent watches mails.list_threads for replies on the review thread, parses the typed events for intent (approval, rejection, change_request), and reacts.
Documentation request triage. Agent reads incoming doc-request emails as typed events, drafts updates, and replies via mails.send.
Incident response notification. Background agent monitoring production sends notifications to the on-call rotation when anomalies fire.

Security considerations

Per-key scope. One mk_live_... key per agent. Compromised key = revoke that one agent. Rotate via api.mails.ai/keys.
Tool refusal under injection. Inbound events include injection_score. When your Cursor agent reads inbound and acts on it, guard the handler: if (event.injection_score > 0.5) return;. See the injection scanning post.
Project vs user scope. Project-level .cursor/mcp.json (gitignored) for project-specific keys. The user-level ~/.cursor/mcp.json applies to all projects on the machine.
Auto-execute discipline. Default Cursor to ask-before-execute on mails.senduntil you have validated the agent’s typical email patterns. Auto-allow only after the workflow is stable.

Read the MCP-native email post for the broader thesis or the Claude Code integration for the same setup with a different config path.

FAQ

Questions developers ask after wiring this up.

How is this different from the Claude Code integration?

The MCP server is identical — same five tools, same JSON config shape, same npm distribution. The only difference is the config file path (~/.cursor/mcp.json vs ~/.claude.json) and the in-IDE preview UX. Cursor's tool execution preview surfaces every mails.* call before execution; you can review the args and confirm before the email actually sends.

Does the agent send emails autonomously, or do I have to approve each one?

Configurable per-Cursor-mode. In Composer / Agent mode, Cursor's auto-execute setting controls whether tools run without approval. Default is 'ask' for new tools — you approve mails.send the first few times, then can mark it 'always allow' if you trust the workflow. We recommend keeping send confirmations on for high-stakes recipients (customers) and auto-allow for low-stakes (yourself, internal addresses).

Can I scope a key to one project?

Yes. Use a per-project .cursor/mcp.json (gitignored) instead of the user-level ~/.cursor/mcp.json. The project-level config takes precedence in that workspace. Your project key never leaks to other projects on the same machine.

Does this work with Cursor's background agents?

Yes. Background agents inherit MCP server registrations from the workspace. The same mails.* tools are available without additional config. Useful for long-running agent tasks that send emails as part of their work — e.g., a documentation-update agent that emails reviewers when a draft is ready.