MCP Server

The official BigFat AI Labs MCP server lets an AI agent work in your BigFat AI Labs project: sending transactional email, managing contacts and segments, and drafting and sending campaigns. It works with both the hosted product and self-hosted instances.

The package is published as @bigfat/mcp.

Setup

You need a secret key (sk_…) from Settings → API Keys. See API Keys for how the two key types differ.

claude mcp add bigfat --env BIGFAT_API_KEY=sk_your_key -- npx -y @bigfat/mcp

{
  "mcpServers": {
    "bigfat": {
      "command": "npx",
      "args": ["-y", "@bigfat/mcp"],
      "env": {
        "BIGFAT_API_KEY": "sk_your_key"
      }
    }
  }
}

{
  "mcpServers": {
    "bigfat": {
      "command": "npx",
      "args": ["-y", "@bigfat/mcp"],
      "env": {
        "BIGFAT_API_KEY": "sk_your_key",
        "BIGFAT_API_URL": "https://api.your-domain.com"
      }
    }
  }
}

Configuration

Available tools

Read-only — the only tools registered when BIGFAT_READ_ONLY=true:

bigfat_list_contacts, bigfat_get_contact, bigfat_verify_email, bigfat_list_templates, bigfat_list_campaigns, bigfat_get_campaign, bigfat_get_campaign_stats, bigfat_list_segments, bigfat_list_domains, bigfat_check_domain

Writing:

bigfat_create_contact, bigfat_update_contact, bigfat_subscribe_contact, bigfat_unsubscribe_contact, bigfat_delete_contact, bigfat_send_email, bigfat_track_event, bigfat_create_template, bigfat_create_campaign, bigfat_test_campaign, bigfat_send_campaign, bigfat_cancel_campaign, bigfat_create_segment

Safety

A BigFat AI Labs secret key grants full access to its project, so the server adds its own limits on top:

• Sends ask for confirmation. Sending a campaign, or an email to more than one recipient, prompts you first and tells you how many people will receive it. Confirmation is not something the model can supply itself — it comes from you, through your MCP client. A client that cannot show a prompt cannot send.
• Read-only mode is structural. With BIGFAT_READ_ONLY=true the mutating tools are never registered, so they cannot be invoked even by name.
• Account-level actions are out of reach. Billing, project deletion, and key rotation all require a dashboard session rather than an API key, so no tool can reach them.

Use a separate project for anything you would rather an agent could not change, and rotate the key (Settings → API Keys) if you stop trusting a machine that held it. Note that rotation replaces both keys at once.

Things to know

Transactional versus campaign. bigfat_send_email is for one-off messages to specific people. Reaching a whole list means creating a campaign and then sending it. The agent is instructed not to loop sends over an audience, which would hit the rate limit and skip unsubscribe handling.

Verified domains. Sender addresses must be on a domain verified for the project, or the send is rejected. bigfat_list_domains lets the agent check before it sends, and bigfat_check_domain re-runs the DNS check after you add records. Adding and removing domains stays in the dashboard — those endpoints skip the admin-role check for API keys, so exposing them would give an agent authority a non-admin member does not have. See Verifying domains.

Unsubscribing someone. bigfat_unsubscribe_contact takes an email address directly, so "unsubscribe ada@example.com" is a single call. It matches exactly and case-insensitively rather than patching the first result of a substring search. bigfat_subscribe_contact reverses it, but only for a contact that already exists — opting someone in never creates a new record.

Testing before a campaign goes out. bigfat_test_campaign sends one copy for review. The recipient must be a member of the BigFat AI Labs project; any other address is rejected. If a send is already scheduled or in flight, bigfat_cancel_campaign stops whatever has not gone out yet — it cannot recall what has.

Event tracking. /v1/track requires the public key. Without BIGFAT_PUBLIC_KEY the server gets the same result using the secret key, creating or updating the contact first and then recording the event. Either way the contact is created if it does not exist.