Windsurf·MCP server·4 min read

Mails.ai for Windsurf — drop-in MCP server in Cascade

MCP serveradd to ~/.codeium/windsurf/mcp_config.json

Add to ~/.codeium/windsurf/mcp_config.json. Open Windsurf → Settings → MCP Servers to verify.

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

Windsurf is Codeium’s standalone AI-native IDE built around the Cascade autonomous agent. Add the mails.ai MCP server to ~/.codeium/windsurf/mcp_config.json and Cascade auto-discovers the same five mails.* tools for use in plan mode (review-before-execute) or write mode (autonomous loop).

Why Windsurf + mails.ai

Cascade’s strength is long-horizon autonomous work — multi-step tasks spanning hours, with checkpoints, memory, and recovery. Adding email as an MCP tool means Cascade can:

Send progress notificationsduring long-running refactors or analyses (“refactoring complete, here’s the diff link”).
Read incoming feedback via mails.list_threads mid-task and adapt the plan based on stakeholder input.
Triage and reply to PR review comments received as email notifications, by reading the typed event and acting on the intent field.
Coordinate with humans across timezones— pause work, email a question, resume when the reply lands.

Setup

Get an API key. api.mails.ai/keys at Phase 1 launch, or request a closed-beta key from support@mails.ai.
Edit ~/.codeium/windsurf/mcp_config.json.Create the file if it doesn’t exist. Add the snippet from the install card. Replace mk_live_... with your key.
Restart Windsurf.Open Settings → MCP Servers to verify the server is registered with five tools listed.
Set Cascade’s approval mode for the workspace.Recommended: manual approval until you trust the agent’s mail-handling behavior.

First commands to test

# In Cascade
> What mails.* tools are available?

# Plan-mode test
> Plan a test email send: use mails.send from agent "test" to email myself "Cascade test".

# After approving the plan, Cascade executes
> Execute the plan.

# Verify
> Use mails.list_threads to confirm the test send.

Common patterns

Long-horizon checkpoint emails.Cascade tasks running over hours benefit from periodic email checkpoints — helps you verify progress without watching the IDE.
Per-rule allowlist for autonomous send.Cascade’s rules engine can enforce “mails.send only to @yourcompany.com” or similar. Constrains autonomous behavior to known-safe destinations.
Memory-aware reply handling. When Cascade reads a thread via mails.list_threadsand the typed event includes prior conversation context, Cascade’s memory layer can correlate it with task state — useful for multi-day stakeholder coordination.

Security considerations

Approval mode discipline.Cascade’s autonomous loop is powerful. Default to manual approval for any send that hits external addresses. Auto-approval only for self-test or sandboxed workspaces.
Volume cap via system prompt.Until per-agent budgets ship (Phase 1.5), include “send no more than 5 emails per session” in your Cascade system prompt for any agent with mails.* tools enabled.
Memory persistence + injection. If your agent reads an inbound with high injection_score, the typed event itself is logged in Cascade’s memory. Even with the score-guard preventing action, the malicious payload sits in the agent’s context. Manually clear memory if you process suspicious inbound.

Compare against Cline, Continue, or Cursor for other MCP-runtime IDE setups.

FAQ

Questions developers ask after wiring this up.

Does Cascade auto-call mails.* tools without approval?

Depends on your Cascade approval mode. Default 'manual approval' surfaces every tool call for review before execution — useful for any high-stakes mail. 'Auto-approval' runs tools without confirmation — appropriate for sandboxed workspaces or tools you have validated. We recommend manual approval for anything that hits customer addresses; auto-approval for self-test sends.

Cascade can run for hours autonomously. Will it spam my customers?

Per-agent send budgets ship in Phase 1.5 — set a hard cap of N sends per hour or per day per agent, enforced platform-side. Until then, use the suppression list aggressively (mails.suppress on any address that has previously bounced or complained), and set a system prompt instruction explicitly limiting send volume per session.

What about Windsurf's memory / preview window features?

Windsurf's memory layer remembers task context across sessions. mails.* tool calls are part of that context — Cascade remembers it has emailed a particular address recently and may use that history when planning subsequent sends. Useful for thread continuity (referring to prior conversation) but watch for the agent re-emailing addresses unnecessarily.

Does this work with Codeium's non-Windsurf products (e.g., Codeium for VS Code)?

The MCP server itself is product-agnostic, but Codeium's VS Code extension does not currently expose MCP server configuration the same way Windsurf does. If you want mails.ai in Codeium-for-VS-Code, use the SDK directly. Cline or Continue (also VS Code) ARE MCP-capable — see those integration guides.