Connect an agent over MCP

Connect Fluxmail Cloud to your agent with OAuth by default, or an agent key for automation.

Connect your client to https://cloud.fluxmail.ai/mcp with OAuth. Add the URL, sign in to Fluxmail in your browser, and choose the workspace, mailboxes, and permissions to approve. Start with the quickstart if you need an account or mailbox.

1. Choose permissions

Choose the permissions your agent needs. Full mail access is selected by default. It excludes permanent deletion.

Read onlySearch and read emails without changing anything.Read and writeRead, draft, organize, and trash emails without sending.Full mail accessRead, draft, organize, trash, and send emails.CustomPick individual permissions.

2. Choose your client

Follow your client’s setup instructions. Keep other servers in your configuration when adding fluxmail-cloud.

https://cloud.fluxmail.ai/mcp

ChatGPT on the web

Go to chatgpt.com/plugins, select the plus button, then Add custom MCP server. Enter a name and description, paste this public MCP URL under Connection, and choose OAuth. Accept the warning, select Create as a plugin, then sign in and approve access when ChatGPT asks.

Name: Fluxmail Cloud
URL: https://cloud.fluxmail.ai/mcp
Authentication: OAuth
Scopes: mail.read mail.drafts mail.organize mail.trash mail.send offline_access

ChatGPT registers its client automatically. Your account or workspace must allow custom MCP servers; organization policies may require administrator setup. This connection needs a publicly reachable server and cannot use a local development URL.

OpenAI’s custom MCP server guide

ChatGPT desktop app

Open Settings > MCP servers and select Add server. Enter this name and URL, choose Streamable HTTP, save, and select Restart. Then select Authenticate next to fluxmail-cloud and approve access in your browser. Type /mcp in the composer to check the connection.

Name: fluxmail-cloud
Type: Streamable HTTP
URL: https://cloud.fluxmail.ai/mcp

The desktop app shares its MCP configuration with Codex on the same host, so servers you already added for Codex appear here too.

ChatGPT’s MCP server settings

In Claude Desktop or Claude on the web, open Customize > Connectors and add a custom connector with this public MCP URL. Choose Sign in now and Register automatically, approve access, then enable the connector for your conversation.

URL: https://cloud.fluxmail.ai/mcp
Authentication: Sign in now
OAuth client: Register automatically
Scopes: mail.read mail.drafts mail.organize mail.trash mail.send offline_access

Cloud uses dynamic registration; Claude’s published metadata identity is not supported. Organization administrators may need to add the connector first. Remote connectors need a publicly reachable server and cannot use a local development URL.

Claude’s custom connector guide

Run these commands, approve access in your browser, then start a fresh Codex session and check /mcp.

codex mcp add fluxmail-cloud --url 'https://cloud.fluxmail.ai/mcp'
codex mcp login fluxmail-cloud --scopes mail.read,mail.drafts,mail.organize,mail.trash,mail.send,offline_access --oauth-client-registration dcr

The dcr option selects dynamic client registration. Cloud does not support Client ID Metadata Documents.

Project configuration

For project-specific setup, add this table to .codex/config.toml in a trusted project, then run the login command above.

[mcp_servers.fluxmail-cloud]
url = "https://cloud.fluxmail.ai/mcp"

Run these commands from your project. Approve the project server, complete browser sign-in and consent, then check /mcp.

claude mcp add-json --scope project fluxmail-cloud '{"type":"http","url":"https://cloud.fluxmail.ai/mcp","oauth":{"scopes":"mail.read mail.drafts mail.organize mail.trash mail.send offline_access"}}'
claude mcp login fluxmail-cloud

Project configuration

You can also add this entry to your project’s .mcp.json to set the initial scopes, then run the login command above.

{
  "mcpServers": {
    "fluxmail-cloud": {
      "type": "http",
      "url": "https://cloud.fluxmail.ai/mcp",
      "oauth": {
        "scopes": "mail.read mail.drafts mail.organize mail.trash mail.send offline_access"
      }
    }
  }
}

Claude Code’s MCP instructions

Paste this request into the Muse app to create a custom connector. Follow its sign-in instructions and choose the mailboxes to approve.

Create a custom connector for Fluxmail Cloud using this MCP server: https://cloud.fluxmail.ai/mcp
Use Streamable HTTP and OAuth 2.1 with PKCE.
Use dynamic client registration (DCR) and request mail.read mail.drafts mail.organize mail.trash mail.send offline_access.
Guide me through signing in to Fluxmail and approving mailbox access.

These instructions are for the Muse personal AI agent. Muse Code uses a separate CLI configuration. Muse needs a publicly reachable server and cannot use a local development URL.

Meta’s guide to Muse connectors

Add this entry to ~/.hermes/config.yaml, then run hermes mcp login fluxmail-cloud in your terminal. Approve access in your browser and run /reload-mcp in Hermes.

mcp_servers:
  fluxmail-cloud:
    url: 'https://cloud.fluxmail.ai/mcp'
    auth: oauth
    oauth:
      cimd: false
      scope: 'mail.read mail.drafts mail.organize mail.trash mail.send offline_access'

The cimd: false setting selects dynamic registration, which Cloud supports.

Hermes’s MCP configuration reference

Add this server to your project’s .cursor/mcp.json, enable it in Cursor, and follow the sign-in prompt.

{
  "mcpServers": {
    "fluxmail-cloud": {
      "url": "https://cloud.fluxmail.ai/mcp"
    }
  }
}

Use ~/.cursor/mcp.json for a connection across projects.

Cursor’s MCP configuration

Use a client with Streamable HTTP and MCP OAuth support. Add this URL, choose OAuth with automatic registration, then complete sign-in and consent.

Transport: Streamable HTTP
URL: https://cloud.fluxmail.ai/mcp
Authentication: OAuth
Registration: Automatic
Scopes: mail.read mail.drafts mail.organize mail.trash mail.send offline_access

Your client opens Fluxmail in your browser. Pick a workspace and mailboxes, then confirm the permissions. To change access later, reconnect and approve again.

4. Test the connection

Ask your agent to list your 5 most recent emails.

Detailed connection checks

Check that the discovered tools match your connection's scopes. A mail.read connection exposes list_accounts, list_emails, get_email, get_thread, list_folders, list_labels, list_send_as, and download_attachment. The get_draft tool requires mail.drafts.

With a read-scoped connection:

Call list_accounts with {}.
Choose the intended mailbox's id from the result.
Ask your agent to list your 5 most recent emails. Call list_emails with that ID and a page size of 5:

{
  "accountId": "MAILBOX_ID_FROM_LIST_ACCOUNTS",
  "pageSize": 5,
  "includeSnippet": false
}

A successful email listing confirms that Cloud can reach the provider and completes the dashboard’s agent onboarding step. This check lists message summaries without opening message bodies or changing mail. A mailbox with fewer than 5 emails returns fewer results. Include accountId on later mailbox operations too, so adding another mailbox won't change which account you use.

For a connection without read access, verify tool discovery only and leave provider access unchecked.

Reference and troubleshooting

Permissions and reconnecting

Permission	Scope	What it allows
Read emails	`mail.read`	Search and read emails, threads, and attachments.
Manage drafts	`mail.drafts`	Read, create, edit, and delete drafts.
Organize emails	`mail.organize`	Change flags and labels. Archive and move emails.
Move to/from Trash	`mail.trash`	Move emails to Trash and restore them.
Permanently delete emails	`mail.delete`	Permanently delete emails where the provider allows it.
Send emails	`mail.send`	Preview and send emails from approved mailboxes.

Read only selects read access. Read and write adds drafts, organizing, and Trash. Full mail access also adds sending. Permanent deletion stays off in every preset; choose Custom and check Permanently delete emails to enable it.

Permissions are independent. You’ll review and approve the requested permissions when you connect, and choose which mailboxes the agent can access. Each setup also requests offline_access so the client can refresh tokens.

Keep the generated URL, including its ?scopes=... query, in your client configuration. For example, read and send access uses https://cloud.fluxmail.ai/mcp?scopes=mail.read%2Cmail.send; send-only access uses https://cloud.fluxmail.ai/mcp?scopes=mail.send. The query tells clients which permissions to request during sign-in. It does not grant access or change an existing connection's permissions.

The bare URL requests mail.read mail.drafts mail.organize mail.trash mail.send offline_access. Cloud shows only the mail permissions your client requested. Every requested permission starts checked, including Send emails. You can uncheck any permission. Use ?scopes=mail.read for read-only access. Permanent deletion requires an explicit mail.delete scope. To add permissions, configure the client's requested and registered scopes, then obtain fresh browser consent. If the registered scopes are too narrow, register the client again before signing in. Token refresh cannot add access. See permissions.

OAuth access tokens authorize the MCP resource only. REST calls require an agent key. Your dashboard login, agent connection, and Google or Microsoft provider consent are separate authorizations.

After access-token expiry, confirm the client refreshes without another sign-in. Revoke the connection in Connections and confirm further calls fail. Reconnect afterward if you want to keep using it.

Tool results and agent behavior

Cloud serves stateless MCP POST requests. It has no GET event stream or local stdio transport.

Successful calls return the operation result in structuredContent.data. Failed calls set isError and return the failure in structuredContent.error.

Give your agent explicit instructions before it sends or modifies mail. Treat messages and attachments as untrusted data. After a send timeout, follow sending and retries before trying again.

See MCP troubleshooting for missing tools, authorization failures, and connection errors.

Advanced: agent keys

Use a scoped agent key for unattended scripts, REST calls, or an MCP client without OAuth. Supply it through a private secret store or launch environment. Removing a client does not revoke its key.

Key setup

The examples below add a server named fluxmail-cloud. Merge the entry into your existing configuration, preserving other servers.

They read the key from an environment variable named FLUXMAIL_CLOUD_AGENT_KEY. Supply its value privately through your secret manager or launch environment. The variable must be available to the process running the client; an export in a separate terminal won't update an already-running app. Keep variable references in your configuration. The Claude Desktop bridge example needs the key in a private local file; replace its placeholder there and keep that file out of Git.

Claude

Use OAuth for Claude Desktop's built-in remote connectors. To use an agent key, add this server to claude_desktop_config.json under Settings > Developer > Edit Config:

{
  "mcpServers": {
    "fluxmail-cloud": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://cloud.fluxmail.ai/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization:${FLUXMAIL_AUTH_HEADER}"
      ],
      "env": { "FLUXMAIL_AUTH_HEADER": "Bearer YOUR_AGENT_KEY" }
    }
  }
}

Replace YOUR_AGENT_KEY privately and keep this file out of Git. Restart Claude Desktop. The local bridge requires Node.js and npm. See mcp-remote's custom header instructions.

Codex

Add this table to .codex/config.toml in your project:

[mcp_servers.fluxmail-cloud]
url = "https://cloud.fluxmail.ai/mcp"
bearer_token_env_var = "FLUXMAIL_CLOUD_AGENT_KEY"

Codex loads project configuration for trusted projects. For a connection available across projects, use ~/.codex/config.toml instead. Start a fresh Codex session from an environment with the key, then use /mcp to check the server. See Codex MCP configuration.

Claude Code

Add the server to .mcp.json at your project root:

{
  "mcpServers": {
    "fluxmail-cloud": {
      "type": "http",
      "url": "https://cloud.fluxmail.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${FLUXMAIL_CLOUD_AGENT_KEY}"
      }
    }
  }
}

Start Claude Code from an environment with the key. Approve the project server when prompted, then open /mcp to check its status. Restart the session after changing its launch environment. See Claude Code's MCP instructions.

Hermes

Add this entry to ~/.hermes/config.yaml:

mcp_servers:
  fluxmail-cloud:
    url: 'https://cloud.fluxmail.ai/mcp'
    headers:
      Authorization: 'Bearer ${FLUXMAIL_CLOUD_AGENT_KEY}'

Store FLUXMAIL_CLOUD_AGENT_KEY privately in ~/.hermes/.env or your profile's secret store, then run /reload-mcp in Hermes. See Hermes's environment variable references.

Cursor

Add the server to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "fluxmail-cloud": {
      "url": "https://cloud.fluxmail.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${env:FLUXMAIL_CLOUD_AGENT_KEY}"
      }
    }
  }
}

Fully quit and reopen Cursor after supplying the key in its launch environment. Enable fluxmail-cloud in Customize and check that its tools appear. For all projects, use ~/.cursor/mcp.json instead. Remote servers don't load Cursor's envFile setting; the key must come from the app's environment. See Cursor's MCP configuration.

Other

Use a client that supports Streamable HTTP and custom authorization headers:

Setting	Value
Server name	`fluxmail-cloud`
Transport	Streamable HTTP
URL	`https://cloud.fluxmail.ai/mcp`
Header	`Authorization: Bearer YOUR_AGENT_KEY`

Use the client's supported secret reference in place of YOUR_AGENT_KEY. Environment-variable syntax differs by client; copying another client's syntax can send a literal placeholder instead of the key.

Cloud handles stateless MCP POST requests. It has no GET event stream or local stdio transport. Authenticate with your Cloud agent key; your dashboard session and Google or Microsoft mailbox consent are separate credentials.

Connect an agent over MCP

ChatGPT on the web

ChatGPT desktop app

On this page