MCP Integration

What Is the MCP Server?

Mailgator includes a built-in MCP (Model Context Protocol) server. Run mailgator mcp and it starts on stdin/stdout, ready to accept commands from any MCP-compatible AI coding assistant.

This means AI assistants like Claude Code, Gemini CLI, and OpenAI Codex can fully manage your Mailgator configuration through natural language. No manual TOML editing required — just describe what you want and the AI handles the rest.

  • Add, remove, and reorder rules without touching the config file
  • Test which rule matches a given email scenario before deploying
  • Browse built-in documentation on operations, patterns, and examples
  • Validate your config and catch errors early

Available MCP Tools

The MCP server exposes the following tools to connected AI assistants:

Tool Description
get_config Returns the current config as JSON. Secrets are redacted.
validate_config Validates the config and returns a list of errors, if any.
set_service Configure SMTP or IMAP upstream addresses and TLS mode.
list_rules List all rules with their names, actions, and positions.
add_rule Add a new rule at a specific position in the rule list.
update_rule Update an existing rule by name. Supports partial updates — only the fields you specify are changed.
remove_rule Remove a rule by name.
move_rule Reorder a rule to a new position. Rule order matters — the first matching rule wins.
configure_ask Set up the ask approval workflow: timeout, retention, base URL, and approval groups.
simulate Test which rule matches a given email scenario (from, to, folder, operation) without modifying anything.
get_reference Browse built-in documentation on operations, patterns, rules, ask, TLS, and examples.

Setup with Claude Code

Add a .mcp.json file to your project root:

// .mcp.json (in your project root)
{
  "mcpServers": {
    "mailgator": {
      "command": "mailgator",
      "args": ["mcp", "-c", "/path/to/mailgator-config.toml"]
    }
  }
}

Then just ask Claude: "Add a rule that allows the AI to read invoices but nothing else" — and it will use the MCP tools to make it happen.

Setup with Gemini CLI

Add the Mailgator server to your Gemini CLI settings file at .gemini/settings.json:

// .gemini/settings.json
{
  "mcpServers": {
    "mailgator": {
      "command": "mailgator",
      "args": ["mcp", "-c", "/path/to/mailgator-config.toml"]
    }
  }
}

Setup with OpenAI Codex CLI

Add the Mailgator server to your Codex config file at .codex/config.json:

// .codex/config.json
{
  "mcpServers": {
    "mailgator": {
      "command": "mailgator",
      "args": ["mcp", "-c", "/path/to/mailgator-config.toml"]
    }
  }
}

Example Conversations

Here are a few examples of what you can ask your AI assistant once Mailgator MCP is connected:

Prompt

"Set up Mailgator for Gmail with read-only access for my AI agent"

What the AI does

  • Calls set_service to configure imap.gmail.com:993 with TLS and smtp.gmail.com:587 with STARTTLS
  • Calls add_rule to allow read, list, and search operations
  • Calls add_rule to deny all mail:send operations as a catch-all
  • Calls validate_config to confirm no errors before finishing

Prompt

"Add a rule that requires approval before sending any external emails"

What the AI does

  • Calls list_rules to understand the current rule order
  • Calls configure_ask to set up the approval workflow if not already configured
  • Calls add_rule with action = "ask" and the appropriate ask_groups
  • Positions the rule before the catch-all deny rule using move_rule if needed

Prompt

"Which rule would match if my agent tries to read emails in the Invoices folder?"

What the AI does

  • Calls simulate with operation = "read" and folder = "Invoices"
  • Reports back which rule matched, what action it triggers, and why
  • Suggests adjustments if the result is not what you intended
Ask & Approval Deployment