Connect an MCP client

Complete the Quickstart before configuring an MCP client.

Choose one transport

Configure either stdio or Streamable HTTP. You do not need both.

For most local setups, choose stdio. Choose Streamable HTTP when Fluxmail runs in Docker, on another machine, or when the client requires a URL.

Both transports provide the same MCP tools. The examples use the default full permission profile. See Permissions if the client should have less access.

Option 1: Connect over stdio

Every stdio client launches fluxmail stdio. Fluxmail uses the member logged in to the selected local instance. You do not need to run fluxmail serve.

claude mcp add fluxmail -- fluxmail stdio

Add this server to claude_desktop_config.json under Settings > Developer > Edit Config:

{
  "mcpServers": {
    "fluxmail": {
      "command": "fluxmail",
      "args": ["stdio"]
    }
  }
}

Open Settings > Plugins > MCPs > Add server, then enter:

• Name: Fluxmail
• Type: STDIO
• Command to launch: fluxmail
• Arguments: stdio

Save the server and restart the app.

codex mcp add fluxmail -- fluxmail stdio

You can also add the server to ~/.codex/config.toml:

[mcp_servers.fluxmail]
command = "fluxmail"
args = ["stdio"]

Add the server to ~/.cursor/mcp.json, or to .cursor/mcp.json in a project:

{
  "mcpServers": {
    "fluxmail": {
      "command": "fluxmail",
      "args": ["stdio"]
    }
  }
}

Add the server to ~/.hermes/config.yaml, then run /reload-mcp. You can also use the dashboard opened by hermes dashboard.

mcp_servers:
  fluxmail:
    command: 'fluxmail'
    args: ['stdio']

Add the server to ~/.gemini/settings.json:

{
  "mcpServers": {
    "fluxmail": {
      "command": "fluxmail",
      "args": ["stdio"]
    }
  }
}

Register fluxmail as the command with stdio as its argument.

If a desktop client cannot find fluxmail, run which fluxmail in your terminal and use the returned absolute path as the command.

If you configured stdio, continue to Test the connection. Do not configure Streamable HTTP as well.

Option 2: Connect over Streamable HTTP

Use this option instead of stdio when the MCP client connects to Fluxmail by URL.

Start the HTTP server and create an API key for the client:

fluxmail apikey create --name local-agent

fluxmail serve

Fluxmail displays the fmk_... key once. The local MCP URL is http://localhost:8977/mcp. A remote deployment uses its public HTTPS URL followed by /mcp.

If Fluxmail runs in Docker, create the key inside the container. The server is already started by Docker Compose:

docker compose exec fluxmail \
  fluxmail apikey create --name desktop

claude mcp add --transport http fluxmail http://localhost:8977/mcp \
  --header "Authorization: Bearer fmk_..."

Claude Desktop's built-in remote connectors accept OAuth or no authentication, so they cannot send a Fluxmail API key. Use the local mcp-remote bridge.

Add this server to claude_desktop_config.json under Settings > Developer > Edit Config:

{
  "mcpServers": {
    "fluxmail": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "http://localhost:8977/mcp",
        "--allow-http",
        "--transport",
        "http-only",
        "--header",
        "Authorization:${FLUXMAIL_AUTH_HEADER}"
      ],
      "env": {
        "FLUXMAIL_AUTH_HEADER": "Bearer fmk_..."
      }
    }
  }
}

Replace fmk_... with the API key, then restart Claude Desktop. The bridge requires Node.js and npm on the same computer as Claude Desktop.

Open Settings > Plugins > MCPs > Add server, then enter:

• Name: Fluxmail
• Type: Streamable HTTP
• URL: http://localhost:8977/mcp
• Header name: Authorization
• Header value: Bearer fmk_...

Save the server and restart the app.

Add the server to ~/.codex/config.toml:

[mcp_servers.fluxmail]
url = "http://localhost:8977/mcp"
http_headers = { Authorization = "Bearer fmk_..." }

Add the server to ~/.cursor/mcp.json, or to .cursor/mcp.json in a project:

{
  "mcpServers": {
    "fluxmail": {
      "url": "http://localhost:8977/mcp",
      "headers": { "Authorization": "Bearer fmk_..." }
    }
  }
}

Add the server to ~/.hermes/config.yaml, then run /reload-mcp:

mcp_servers:
  fluxmail:
    url: 'http://localhost:8977/mcp'
    headers:
      Authorization: 'Bearer fmk_...'

Add the server to ~/.gemini/settings.json:

{
  "mcpServers": {
    "fluxmail": {
      "httpUrl": "http://localhost:8977/mcp",
      "headers": { "Authorization": "Bearer fmk_..." }
    }
  }
}

The ChatGPT / Codex app entry above configures Codex inside the ChatGPT app. Developer-mode apps used from regular ChatGPT chats have separate settings.

ChatGPT cannot connect directly to localhost. For a local Docker server, use OpenAI's Secure MCP Tunnel. You can also deploy Fluxmail at a public HTTPS URL.

ChatGPT connectors currently support OAuth or no authentication, so they cannot send Fluxmail's API key. Fluxmail does not offer an unauthenticated MCP mode. ChatGPT developer-mode apps are not compatible until Fluxmail supports MCP OAuth.

Point the client to http://localhost:8977/mcp, or to the deployed /mcp URL. Send Authorization: Bearer fmk_... with each request.

Clients that cannot set an authorization header are not compatible with the HTTP MCP endpoint.

Test the connection

Ask the connected agent:

What are the latest 5 emails in my inbox?

If the agent returns the messages, the connection is working. See MCP tools for the operations it can call.

Limit access

For stdio, add --profile read-only, --profile read-write, or repeated --allow options to the server command.

For HTTP, the API key stores the permission profile and mailbox scope. You can change them without updating the client configuration. See Permissions for profiles and capabilities.