Connect an AI agent with MCP

Fluxmail speaks the Model Context Protocol (MCP), so you can point an outside AI agent like ChatGPT, Claude, Cursor, Claude Code, or Codex at your mail. Connect once and the agent can work across every Gmail account you've already added to Fluxmail. There's nothing new to authorize in Gmail: the agent uses the access you granted when you connected each account.

How to connect

Pick one, based on what your client supports. OAuth is the easiest when your client offers it; use an API key for clients that only take a URL or a token.

Option 1: Sign in over OAuth (recommended)

In a client that supports remote MCP servers over OAuth, paste your server URL:

https://fluxmail.ai/api/mcp

The client sends you to Fluxmail to sign in and approve access, then connects. There's no key to copy or store. On the approval screen you can also turn on read-only (so the agent can read and search but can't send or change anything) and choose which accounts it can reach (all, one, or several). You can adjust both later from Settings → MCP.

Option 2: Use an API key

For a client that only takes a URL or a token (a script, a CLI agent, a self-hosted setup). First create the key:

1. Open Settings → MCP and choose New key.
2. Name it, pick which accounts it can reach (all, one, or several), and decide whether it's read-only.
3. Copy the key. You'll see it once.

Then give the key to your client whichever way it supports. You only need one of these:

• Bearer token (preferred):

  Authorization: Bearer flux_your_key_here
  

• x-api-key header (some clients label this field "API key" or "token"):

  x-api-key: flux_your_key_here
  

• Key in the URL, for a client that only accepts a plain URL:

  https://fluxmail.ai/api/mcp/flux_your_key_here
  

  Treat that URL like a password: anyone who has it can act on your mail.

• Config file (Claude Desktop, Cursor, Codex CLI, and similar):

  {
    "mcpServers": {
      "fluxmail": {
        "url": "https://fluxmail.ai/api/mcp",
        "headers": { "Authorization": "Bearer flux_your_key_here" }
      }
    }
  }
  

Revoke a key the moment you suspect it's leaked. Revoking takes effect immediately.

What the agent can do

Once connected, the agent has tools to:

• Read and search: list your accounts, search with Gmail's query syntax, open a thread, list labels, look up contacts and saved drafts.
• Triage: archive, move back to the inbox, mark read or unread, star, add or remove labels, snooze, trash, or mark spam.
• Draft: write a new draft or a reply, or revise an existing draft. Drafts are saved in Fluxmail.
• Send: send a new message, a reply, or a forward, or schedule one for later. Sending clients ask you to confirm first.
• Manage rules: list, create, update, or delete your Fluxmail rules.

If you've connected more than one account, you can mention which account you want to target.

What shows up where

• In Gmail and on all your devices: archive, move to inbox, read/unread, star, labels, trash, spam, and real sends. These go straight through Gmail.
• In Fluxmail only: drafts (saved in Fluxmail, not Gmail's Drafts folder), rules (Fluxmail's own automation, not Gmail filters), snoozes, and scheduled sends (queued in Fluxmail; they become a real Gmail message when they go out).

Staying in control

• Read-only access lets an agent search and read but not send, trash, or change anything, which is a safe choice for when you just want to ask questions. Set it when you create an API key or when you approve an OAuth app, and switch a connected app between read-only and full access later in Settings → MCP. The change applies to its next request, so there's nothing to reconnect.
• Account access limits an agent to the mailboxes you choose: all of them, one, or a few. Set it when you create an API key or approve an OAuth app, and change a connected app's accounts later in Settings → MCP. Like read-only, the change applies to the next request.
• Consequential actions (sending, trashing, deleting a rule) are marked so your agent asks you to confirm before it goes ahead.
• Revoke any time from Settings → MCP. API keys and connected apps both disconnect the instant you revoke them.

Troubleshooting

• "Payment required", or the client won't connect at all: The MCP server is part of a paid plan. It starts working once you have an active plan or trial. Start one in Billing, then connect again.
• "Unauthorized", or the connection is rejected: The key or token is missing, wrong, expired, or revoked. Create a fresh key in Settings → MCP, or reconnect over OAuth. An OAuth app you revoked has to approve access again.
• The agent says it needs an account, or can't find one: With more than one account connected, tell it which account to use. If it still can't reach one, the key or app may be scoped to a different account, so widen its accounts in Settings → MCP.
• The agent can't send, trash, or change anything: It's connected read-only. Switch it to full access in Settings → MCP (the change applies to its next request), or use a full-access key.
• A send or delete stopped to ask you first: That's expected. Consequential actions are marked so your client confirms with you before going ahead. Approve the prompt to continue.