Documentation/AI agents & assistants/Cursor

Using MailFlat with Cursor

Give Cursor's agent a real inbox: add the MailFlat MCP server to your project or user config and it can register test accounts and read the codes on its own.

How it fits together

Cursor reads MCP servers from two places: a per-project file the whole team shares, and a personal one that follows you between projects. Which you pick decides who gets the API key, so it is worth deciding on purpose rather than by accident.

Project scope

Everyone who opens the repository gets the server. Use it when the inbox is part of how the project is tested.

JSON

// .cursor/mcp.json
{
  "mcpServers": {
    "mailflat": {
      "command": "uvx",
      "args": ["mailflat-mcp"],
      "env": { "MAILFLAT_API_KEY": "mf_live_..." }
    }
  }
}

Add .cursor/mcp.json to .gitignore, or commit it with the key removed and let each person fill in their own.

User scope

Same block, personal file: the server is available in every project you open and the key never goes near the repository. This is the safer default.

Shell

mkdir -p ~/.cursor
$EDITOR ~/.cursor/mcp.json

Check that Cursor picked it up

Settings → MCP lists the server with its tools. A red dot there means the command failed to start; run it in a terminal to see the actual error.

Shell

MAILFLAT_API_KEY=mf_live_... uvx mailflat-mcp

Then ask for the whole flow, not one tool

The tools compose, so the useful prompts describe the outcome. Agent mode will chain create_inbox, wait_for_otp and delete_inbox by itself.

Shell

# In Cursor's agent mode:
#   "Open a MailFlat inbox with the label cursor-signup, sign up for
#    staging.example.com with that address, read the verification code
#    from the inbox, finish the signup, then delete the inbox."

Worth knowing

A committed .cursor/mcp.json puts a live account key in your git history, where deleting the file later does not remove it. Prefer the user-scope file, or keep the key out of the committed version.

Cursor's agent can run tools without asking once you approve them. delete_inbox permanently removes the messages, so keep production inboxes on a different key than the one the editor holds.

Encrypted inboxes cannot return an OTP to any client — the server cannot read them. Use a normal inbox for anything the agent has to read.

Using MailFlat with Cursor

How it fits together

Project scope

User scope

Check that Cursor picked it up

Then ask for the whole flow, not one tool

Worth knowing

See also