# Bento MCP Server

Connect your favorite AI assistant to Bento and manage your email marketing with natural language.

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that lets AI assistants like Claude, Cursor, and others interact with external tools and services. The Bento MCP server gives your AI assistant direct access to your Bento account. It can look up subscribers, create broadcasts, track events, and more, all through natural conversation.

Bento hosts the MCP server at `https://mcp.bentonow.com/mcp`. You point your AI app at that URL and add your API keys. There's nothing to install, run, or update.

Whether you're drafting a campaign, importing subscribers, or checking your stats, you describe the task and your AI assistant runs the matching Bento tools.


> Hey! If you get lost, click **"View markdown"** and send this page to your agent and have them set it up for you!


> If you also use an AI coding agent to build Bento integrations, install [Bento Skills](/docs/integrations/skills): `npx skills add bentonow/bento-skills`. MCP gives the assistant live account tools; Skills gives it implementation and safety guidance.


---


> **Before you begin, make sure you have:**
> - A Bento account with API access
> - Your Bento API credentials (Publishable Key, Secret Key, Site UUID)
> - An AI application that supports MCP (Claude Desktop, Claude Code, Cursor, VS Code, Codex, Gemini CLI, etc.)
> - Node.js 18 or later, only if your app needs the `mcp-remote` bridge (Claude Desktop JSON config and Continue)


---


## Getting Your API Credentials


**1. Navigate to Settings**


Log into your Bento account and click on **Settings** in the left sidebar.


**2. Access API Keys**


Open **Settings -> API Keys** and find your API keys.


**3. Copy Your Credentials**


You'll need three values:

| Credential | Description | Example |
|------------|-------------|---------|
| **Publishable Key** | Your public API key | `pk_live_abc123...` |
| **Secret Key** | Your private API key (keep this safe!) | `sk_live_xyz789...` |
| **Site UUID** | Your unique site identifier | `site_uuid_here` |


> If you don't see API keys, click "Generate Key" to create a new set.


> 🚨 **Important**
> Keep your Secret Key private! Never commit it to version control or share it publicly. Anyone with your secret key has full API access to your Bento account.


---


## Hosted Endpoint


The hosted server is the recommended way to use Bento MCP. Bento runs and updates it, so you always get the latest tools.

| Setting | Value |
|---------|-------|
| **URL** | `https://mcp.bentonow.com/mcp` |
| **Transport** | Streamable HTTP |
| **Authentication** | Three HTTP headers with your Bento API credentials. No OAuth sign-in. |

Send these headers with every request:


  


Your MCP client sends your credentials with each request. The hosted server uses them to call the Bento API for that request and doesn't store them.


> If your MCP client can't send custom headers to a remote server, use the `mcp-remote` bridge or the Claude Desktop extension. Both still connect to the hosted server. The [local npm package](#alternative-local-npm-package) is also available if you need to run the server on your own machine.


---


## Setup Guides by Platform


Pick your AI application below. Every guide connects to the hosted server at `https://mcp.bentonow.com/mcp`, so there is nothing to install or keep updated. Replace the placeholder values with the credentials from **Settings -> API Keys**.

If your client can send custom headers to a remote MCP server, add the URL and the three headers. If it only launches local servers, use the `mcp-remote` bridge shown in the Claude Desktop and Continue guides. It runs through `npx` and forwards requests to the hosted server. Your app isn't listed? See [Other MCP clients](#other-mcp-clients).


  
    
      
        
        Claude Desktop
      
    
    
      Claude's custom connectors only accept a short list of standard header names, so they can't send Bento's credential headers. Use the Bento extension (MCPB) or the <code>mcp-remote</code> bridge instead. Both connect to the hosted server.

      <h4 className="font-semibold text-ink mb-2">Option 1: Install the Bento extension (recommended)</h4>
      <ol className="list-decimal list-inside space-y-2 mb-3">
        <li>Download <a href="/docs/integrations/mcp/bento-mcp-worker.mcpb" download className="font-semibold text-ink underline underline-offset-4 hover:text-bento-text">bento-mcp-worker.mcpb</a>.</li>
        <li>Open Claude Desktop and go to <strong>Settings → Extensions</strong>.</li>
        <li>Choose <strong>Install Extension</strong> and select the downloaded file.</li>
        <li>Enter your Bento publishable key, secret key, and site UUID when prompted.</li>
        <li>Restart Claude Desktop if the Bento tools don't appear right away.</li>
      </ol>
      You don't need to run a local server or deploy anything.

      <h4 className="font-semibold text-ink mb-2 mt-6">Option 2: Edit the JSON config</h4>
      This option needs Node.js 18 or later because <code>mcp-remote</code> runs through <code>npx</code>. Open your configuration file:
      <pre className="bg-canvas rounded-lg px-3 py-2 font-mono text-xs text-ink mb-3 overflow-x-auto">{`macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\\Claude\\claude_desktop_config.json`}</pre>

      Merge this entry into the top-level <code>mcpServers</code> object. Don't replace the rest of the file.
      
        
      
      Restart Claude Desktop. The <code>bento-remote</code> connector shows up in the chat's connectors menu.
    
  

  
    
      
        
        Claude Code
      
    
    
      Claude Code connects straight to the hosted server over HTTP.

      Add Bento for every project on your machine:
      
        
      

      To share the setup with your team without committing secrets, add a project <code>.mcp.json</code>. Claude Code fills in <code>{'${VAR}'}</code> values from each person's environment:
      
        
      
      Run <code>claude mcp list</code> or <code>/mcp</code> inside Claude Code to confirm Bento is connected.
    
  

  
    
      
        
        Cursor
      
    
    
      Cursor supports remote MCP servers with custom headers.

      <ol className="list-decimal list-inside space-y-2 mb-3">
        <li>Open <code>~/.cursor/mcp.json</code> for all projects, or <code>.cursor/mcp.json</code> in one project. You can also get there from <strong>Cursor Settings → MCP</strong>.</li>
        <li>Add the configuration below.</li>
        <li>Check that Bento shows as connected in <strong>Cursor Settings → MCP</strong>.</li>
      </ol>

      
        
      
      To keep keys out of the file, use <code>{'${env:BENTO_SECRET_KEY}'}</code> style values and set the variables in the environment Cursor starts from.
    
  

  
    
      
        
        VS Code (GitHub Copilot)
      
    
    
      GitHub Copilot agent mode in VS Code supports remote HTTP servers. VS Code can prompt for your keys and store them securely, so they never sit in the file.

      Create <code>.vscode/mcp.json</code> in your workspace, or run <strong>MCP: Open User Configuration</strong> from the Command Palette to add it for every workspace:
      
        
      
      Click <strong>Start</strong> above the server entry, enter your credentials, then open Copilot Chat in <strong>Agent</strong> mode and check the tools list for Bento.
    
  

  
    
      
        
        Windsurf
      
    
    
      Windsurf's Cascade agent connects to remote MCP servers with the <code>serverUrl</code> field.

      Open the raw <code>mcp_config.json</code> from Cascade's MCP settings. Its location depends on your version:
      <pre className="bg-canvas rounded-lg px-3 py-2 font-mono text-xs text-ink mb-3 overflow-x-auto">{`Windsurf:                ~/.codeium/windsurf/mcp_config.json
Devin Desktop (Cascade): ~/.config/devin/mcp_config.json
Devin Desktop (Windows): %APPDATA%\\devin\\mcp_config.json`}</pre>

      
        
      
      Header values can use <code>{'${env:BENTO_SECRET_KEY}'}</code> to read from environment variables. Refresh the MCP server list in Cascade after saving.
    
  

  
    
      
        
        ChatGPT and the OpenAI API
      
    
    
      ChatGPT's custom connectors (apps in developer mode) sign in with OAuth or no authentication. They can't send the three Bento credential headers, so you can't add Bento MCP in the ChatGPT app today.

      If you have a ChatGPT plan, use <strong>OpenAI Codex</strong> instead. It's included with ChatGPT plans and connects to Bento MCP directly. See the Codex guide below.

      <h4 className="font-semibold text-ink mb-2">Building with the OpenAI API</h4>
      If you're building your own agent, the Responses API can call the hosted server and pass the headers on each request. Keep the keys on your server.
      
        
      
      Leave <code>require_approval</code> on <code>always</code> while you test so you can review each Bento action before it runs. Swap in whichever model you use.
    
  

  
    
      
        
        OpenAI Codex
      
    
    
      The Codex CLI, IDE extension, and desktop app share one config file and connect straight to the hosted server.

      Add Bento MCP to <code>~/.codex/config.toml</code>:
      
        
      

      <code>env_http_headers</code> reads each value from an environment variable. Start Codex from a shell where your Bento credentials are set:
      
        
      

      If Codex can't inherit environment variables, for example when you launch the desktop app from the Dock, use static headers instead. Keep this file out of source control:
      
        
      

      If the <code>codex</code> shell command isn't available on macOS, the desktop app bundle can run the same check:
      
        
      
    
  

  
    
      
        
        Gemini CLI
      
    
    
      Gemini CLI connects to the hosted server over streamable HTTP.

      Add Bento for your user account:
      
        
      

      Or edit <code>~/.gemini/settings.json</code> (or <code>.gemini/settings.json</code> in a project) directly. Use <code>httpUrl</code>, not <code>url</code>, which is for SSE servers:
      
        
      
      Run <code>/mcp</code> inside Gemini CLI to check that Bento is connected.
    
  

  
    
      
        
        Zed
      
    
    
      Zed supports remote MCP servers. Open <strong>Settings → AI → MCP Servers</strong>, click <strong>Add Server</strong>, and choose <strong>Add Remote Server</strong>. Or add this under <code>context_servers</code> in your Zed <code>settings.json</code>:
      
        
      
      A green dot next to Bento in the Agent Panel settings means the server is running. Bento doesn't use OAuth. If Zed asks you to sign in, set Bento up as a local server that runs the <code>mcp-remote</code> bridge (the same command and args as the Claude Desktop JSON config).
    
  

  
    
      
        
        Cline
      
    
    
      In the Cline panel, open <strong>MCP Servers → Configure</strong> and edit <code>cline_mcp_settings.json</code>. Set <code>type</code> to <code>streamableHttp</code>. If you leave it out, Cline falls back to the older SSE transport.
      
        
      
    
  

  
    
      
        
        Roo Code
      
    
    
      Open the MCP settings from the Roo Code panel and choose <strong>Edit Global MCP</strong> (or <strong>Edit Project MCP</strong> for <code>.roo/mcp.json</code>). Roo Code uses <code>streamable-http</code> as the type:
      
        
      
    
  

  
    
      
        
        OpenCode
      
    
    
      OpenCode connects to remote MCP servers with <code>"type": "remote"</code>. Add this to <code>opencode.json</code> in your project or to <code>~/.config/opencode/opencode.json</code>. <code>{'{env:VAR}'}</code> reads a value from your environment:
      
        
      
    
  

  
    
      
        
        Kiro
      
    
    
      Add Bento to <code>~/.kiro/settings/mcp.json</code> for every workspace, or <code>.kiro/settings/mcp.json</code> for one workspace:
      
        
      
    
  

  
    
      
        
        JetBrains Junie
      
    
    
      Add Bento to <code>~/.junie/mcp/mcp.json</code> for every project, or <code>.junie/mcp/mcp.json</code> in one project:
      
        
      
    
  

  
    
      
        
        LM Studio
      
    
    
      LM Studio 0.3.17 and later support remote MCP servers. Open the <strong>Program</strong> tab, choose <strong>Install → Edit mcp.json</strong>, and add:
      
        
      
    
  

  
    
      
        
        Continue
      
    
    
      Continue (VS Code and JetBrains) runs Bento through the <code>mcp-remote</code> bridge, which forwards requests to the hosted server. It needs Node.js 18 or later.
      Create <code>.continue/mcpServers/bento.yaml</code> in your workspace:
      
        
      
      MCP tools only work in Continue's <strong>Agent</strong> mode.
    
  


## Other MCP clients {{ id: 'other-mcp-clients' }}

Most MCP clients accept one of two shapes. Use the first if your client supports remote servers with headers. Use the second if it only launches local commands.

**Remote server with headers.** The key names vary by client (`url`, `serverUrl`, or `httpUrl`, and sometimes a `type` such as `http` or `streamable-http`). Check your client's docs for the exact names.


  


**Local command through the `mcp-remote` bridge.** This works in any client that can launch a stdio server and needs Node.js 18 or later. Use the same `command`, `args`, and `env` as the [Claude Desktop JSON config](#setup-guides-by-platform).


> Bento MCP doesn't use OAuth. If a client only supports OAuth sign-in for remote servers, use the `mcp-remote` bridge.


---


## Available Tools


The hosted MCP server provides these tools, plus related ones for subscriber status, tag removal, batch events, segment and report stats, and more. Your AI app loads the full list when it connects.


  
    <h3 className="m-0 text-[15px] font-semibold text-ink">Subscriber management</h3>
    
      
        "Look up john@example.com in Bento"
        Look up a subscriber by email or UUID
        <code className="rounded bg-surface-raised px-1.5 py-0.5 font-mono text-xs text-ink-subtle">bento_get_subscriber</code>
      
      
        "Import these 50 subscribers with the 'webinar-attendee' tag"
        Import up to 1000 subscribers at once
        <code className="rounded bg-surface-raised px-1.5 py-0.5 font-mono text-xs text-ink-subtle">bento_batch_import_subscribers</code>
      
      
        "When did jane@example.com last open an email?"
        Get last open, click, and visit times plus recent events
        <code className="rounded bg-surface-raised px-1.5 py-0.5 font-mono text-xs text-ink-subtle">bento_get_subscriber_activity</code>
      
    
  

  
    <h3 className="m-0 text-[15px] font-semibold text-ink">Tags</h3>
    
      
        "What tags do I have in Bento?"
        List all tags in your account
        <code className="rounded bg-surface-raised px-1.5 py-0.5 font-mono text-xs text-ink-subtle">bento_list_tags</code>
      
      
        "Create a tag called 'vip-customer'"
        Create a new tag
        <code className="rounded bg-surface-raised px-1.5 py-0.5 font-mono text-xs text-ink-subtle">bento_create_tag</code>
      
    
  

  
    <h3 className="m-0 text-[15px] font-semibold text-ink">Custom fields</h3>
    
      
        "Show me my custom fields in Bento"
        List all custom fields
        <code className="rounded bg-surface-raised px-1.5 py-0.5 font-mono text-xs text-ink-subtle">bento_list_fields</code>
      
      
        "Create a custom field for 'company_name'"
        Create a new custom field
        <code className="rounded bg-surface-raised px-1.5 py-0.5 font-mono text-xs text-ink-subtle">bento_create_field</code>
      
    
  

  
    <h3 className="m-0 text-[15px] font-semibold text-ink">Event tracking</h3>
    
      
        "Track a 'completed_onboarding' event for user@example.com"
        Track a custom event (can trigger automations)
        <code className="rounded bg-surface-raised px-1.5 py-0.5 font-mono text-xs text-ink-subtle">bento_create_event</code>
      
    
  

  
    <h3 className="m-0 text-[15px] font-semibold text-ink">Broadcasts</h3>
    
      
        "Show me my recent broadcasts"
        List all broadcasts/campaigns
        <code className="rounded bg-surface-raised px-1.5 py-0.5 font-mono text-xs text-ink-subtle">bento_list_broadcasts</code>
      
      
        "Create a broadcast for our spring sale announcement"
        Create a new draft broadcast. Set the sender with <code>authorId</code> or <code>fromName</code> and <code>fromEmail</code>, and add preview text with <code>previewText</code>
        <code className="rounded bg-surface-raised px-1.5 py-0.5 font-mono text-xs text-ink-subtle">bento_create_broadcast</code>
      
      
        "Change the subject of broadcast 456 and send it to the VIP segment"
        Edit a draft or scheduled broadcast. Approving needs a future send time. Check tag names with <code>bento_list_tags</code> first
        <code className="rounded bg-surface-raised px-1.5 py-0.5 font-mono text-xs text-ink-subtle">bento_update_broadcast</code>
      
      
        "Who can I send broadcasts from?"
        List authors to use as the sender
        <code className="rounded bg-surface-raised px-1.5 py-0.5 font-mono text-xs text-ink-subtle">bento_list_authors</code>
      
    
  

  
    <h3 className="m-0 text-[15px] font-semibold text-ink">Render and test emails</h3>
    
      
        "Check the Liquid in broadcast 456 renders for jane@example.com"
        Validate Liquid and preview the rendered email. Never sends
        <code className="rounded bg-surface-raised px-1.5 py-0.5 font-mono text-xs text-ink-subtle">bento_render_email</code>
      
      
        "Send me a test of that broadcast"
        Send a test copy to team members or your sending domains
        <code className="rounded bg-surface-raised px-1.5 py-0.5 font-mono text-xs text-ink-subtle">bento_send_test_email</code>
      
    
  

  
    <h3 className="m-0 text-[15px] font-semibold text-ink">Segments</h3>
    
      
        "Show me the rules in segment seg_12345"
        Fetch a segment and its query
        <code className="rounded bg-surface-raised px-1.5 py-0.5 font-mono text-xs text-ink-subtle">bento_get_segment</code>
      
      
        "Change segment seg_12345 to purchases in the last 60 days"
        Update a segment's name, description, or query. Creating segments is coming soon, so create them in Bento first
        <code className="rounded bg-surface-raised px-1.5 py-0.5 font-mono text-xs text-ink-subtle">bento_update_segment</code>
      
    
  

  
    <h3 className="m-0 text-[15px] font-semibold text-ink">Automations</h3>
    
      
        "What automations do I have set up?"
        List all automations, filtered by sequences, workflows, or all
        <code className="rounded bg-surface-raised px-1.5 py-0.5 font-mono text-xs text-ink-subtle">bento_list_automations</code>
      
    
  

  
    <h3 className="m-0 text-[15px] font-semibold text-ink">Sequences</h3>
    
      
        "Show me all my email sequences"
        List email sequences with their email templates
        <code className="rounded bg-surface-raised px-1.5 py-0.5 font-mono text-xs text-ink-subtle">bento_list_sequences</code>
      
      
        "Add a new email to my Welcome Series sequence about setting up their profile"
        Create a new email in a sequence by ID or name
        <code className="rounded bg-surface-raised px-1.5 py-0.5 font-mono text-xs text-ink-subtle">bento_create_sequence_email</code>
      
      
        "Update the subject line on sequence email template 456"
        Update a sequence email's subject or HTML content
        <code className="rounded bg-surface-raised px-1.5 py-0.5 font-mono text-xs text-ink-subtle">bento_update_sequence_email</code>
      
    
  

  
    <h3 className="m-0 text-[15px] font-semibold text-ink">Workflows</h3>
    
      
        "Show me my workflows"
        List workflows with their status and email templates
        <code className="rounded bg-surface-raised px-1.5 py-0.5 font-mono text-xs text-ink-subtle">bento_list_workflows</code>
      
      
        "Show me the Onboarding workflow"
        Fetch one workflow's structure, triggers, and steps
        <code className="rounded bg-surface-raised px-1.5 py-0.5 font-mono text-xs text-ink-subtle">bento_get_workflow</code>
      
      
        "Add a 2-day wait after the nudge email in Onboarding"
        Propose a change for you to accept in the Flow Builder
        <code className="rounded bg-surface-raised px-1.5 py-0.5 font-mono text-xs text-ink-subtle">bento_propose_workflow_change</code>
      
      
        "Any proposed changes waiting on the Onboarding flow?"
        List pending and outdated proposals for a workflow
        <code className="rounded bg-surface-raised px-1.5 py-0.5 font-mono text-xs text-ink-subtle">bento_list_workflow_proposals</code>
      
    
  

  
    <h3 className="m-0 text-[15px] font-semibold text-ink">Email templates</h3>
    
      
        "Show me template ID 123"
        Get an email template's content by ID
        <code className="rounded bg-surface-raised px-1.5 py-0.5 font-mono text-xs text-ink-subtle">bento_get_template</code>
      
      
        "Update template 123 with this new subject line"
        Update a template's subject, preview text (<code>previewText</code>), or content
        <code className="rounded bg-surface-raised px-1.5 py-0.5 font-mono text-xs text-ink-subtle">bento_update_email_template</code>
      
      
        "Upload this hero image and add it to the template"
        Upload a PNG, JPEG, GIF, or WebP image (base64, up to 1 MB, 20 per day) and get a hosted URL
        <code className="rounded bg-surface-raised px-1.5 py-0.5 font-mono text-xs text-ink-subtle">bento_upload_image</code>
      
    
  

  
    <h3 className="m-0 text-[15px] font-semibold text-ink">Statistics</h3>
    
      
        "How many subscribers do I have?"
        Get overall site statistics
        <code className="rounded bg-surface-raised px-1.5 py-0.5 font-mono text-xs text-ink-subtle">bento_get_site_stats</code>
      
      
        "Which ad campaigns drove the most revenue last month?"
        Query ads attribution by source, campaign, medium, content, or ad
        <code className="rounded bg-surface-raised px-1.5 py-0.5 font-mono text-xs text-ink-subtle">bento_get_ads_stats</code>
      
    
  

  
    <h3 className="m-0 text-[15px] font-semibold text-ink">Delivery troubleshooting</h3>
    
      
        "Any deliverability issues in the last hour?"
        Get transactional delivery health for your account
        <code className="rounded bg-surface-raised px-1.5 py-0.5 font-mono text-xs text-ink-subtle">bento_get_delivery_report</code>
      
      
        "Did our password reset email reach jane@example.com?"
        Search delivery events, bounces, and deferrals for one recipient
        <code className="rounded bg-surface-raised px-1.5 py-0.5 font-mono text-xs text-ink-subtle">bento_search_delivery_events</code>
      
    
  

  
    <h3 className="m-0 text-[15px] font-semibold text-ink">Bento Chat</h3>
    
      
        "Show me unassigned open conversations"
        List support conversations by status, assignment, inbox, or search
        <code className="rounded bg-surface-raised px-1.5 py-0.5 font-mono text-xs text-ink-subtle">bento_list_conversations</code>
      
      
        "Reply to that conversation, then mark it resolved"
        Send replies, add private notes, and change conversation status
        <code className="rounded bg-surface-raised px-1.5 py-0.5 font-mono text-xs text-ink-subtle">bento_send_chat_message</code>
      
    
  


---


## Common Workflows


## Creating an Email Broadcast

This is the most common workflow: drafting and creating an email campaign using natural language.


  
    Create a broadcast called 'Summer Sale Announcement' with the subject 'Save 30% This Weekend Only'. Use HTML format. Send from 'Marketing Team' at marketing@mycompany.com. The content should announce our summer sale with a 30% discount code SUMMER30.
  
  
    I'll create that broadcast for you.
  
  
    Created draft broadcast "Summer Sale Announcement"
    The broadcast is now saved as a draft in your Bento dashboard.
  


> Broadcasts created via MCP are saved as unapproved drafts unless the assistant explicitly sets `approved` to true. Review drafts in the Bento dashboard before they send, and tell your assistant to leave broadcasts unapproved.


> ⚠️ **Warning**
> Tags decide who gets the email, so check them before approving. `inclusiveTags` sends only to subscribers with **all** the listed tags, and `exclusiveTags` leaves out anyone with **any** of them. Names are exact and case-sensitive. A name that doesn't exist becomes a new empty tag, so a typo can empty the audience or let excluded people through. Only the first 20 names count. Ask your assistant to run `bento_list_tags` and copy exact names, then check the audience with `bento_get_broadcast` or in Bento before anything is approved. This applies to `bento_create_broadcast` and `bento_update_broadcast`. See [Tag Targeting](/docs/broadcasts#tag-targeting).


---

## Test an Email, Then Propose a Flow Change

Your assistant can check its own work before anything reaches subscribers. It renders the email, sends you a test copy, and proposes the flow change. Nothing in the flow changes until you click **Accept** in the Flow Builder.


  
    Add a "Still need help?" email 2 days after the nudge email in my Onboarding flow. Check it renders for jane@example.com and send me a test first.
  
  
    Liquid is valid
    
  
  
    Test email queued for me@yourcompany.com
  
  
    Proposed: add a 2-day wait and the "Still need help?" email after the nudge email
    The flow is unchanged. Open the review link to see the change in the Flow Builder.
  
  
    The email renders cleanly and a test is on its way to you. I proposed the change on your Onboarding flow. Open the review link and click Accept in the Flow Builder to apply it. The proposal expires in 7 days.
  


> Your assistant reads the flow with `bento_get_workflow` first and passes its `diagram_revision` as `baseRevision`. If someone saves the flow in between, Bento refuses the proposal, and the assistant reads the flow again and rebuilds the change. A proposal that was already made goes stale when the flow is saved, so ask for a fresh one. Use `bento_list_workflow_proposals` to see pending and stale proposals. See [Workflow Proposals](/docs/workflows_api#workflow-proposals).


> ⚠️ **Warning**
> Test emails only go to your team members' own addresses or addresses on your sending domains, up to 5 per send, and count toward your daily preview limit. Recipients over the limit are skipped and the rest still get the test. Free-mail domains such as gmail.com never count as sending domains.


---

## Importing Subscribers

Perfect for moving subscribers from a spreadsheet or another platform.


  
    Import these subscribers with the tag 'newsletter-2024':
    
• alice@example.com (Alice Smith)
    
• bob@example.com (Bob Jones)
    
• carol@example.com (Carol Williams)
  
  
    I'll import those 3 subscribers with the 'newsletter-2024' tag.
  
  
    Successfully imported 3 of 3 subscribers
  


**Pro Tips for Bulk Imports:**
- You can import up to 1000 subscribers at once
- Custom fields are supported. Just mention them naturally
- Tags can be added or removed during import
- Existing subscribers will be updated (not duplicated)

---

## Tracking Purchase Events

Track revenue and trigger purchase-based automations.


  
    Track a $49.99 purchase for customer@example.com. Order ID is ORD-12345, product is 'Annual Pro Plan'.
  
  
    I'll track that purchase event.
  
  
    Tracked event "$purchase" for customer@example.com
  


> ⚠️ **Warning**
> **Purchase Event Requirements:** Purchase events must include:
> - `value.amount`: Amount in cents (4999 for $49.99)
> - `value.currency`: 3-letter ISO currency code (USD, EUR, etc.)
> 
> The MCP server rejects purchase events without these. Also include a `unique.key`, such as your order ID, so the same purchase isn't counted twice.


---

## Checking Your Stats

Get a quick overview of your Bento account performance.


  
    How is my Bento account doing? Give me the key stats.
  
  
    Retrieved site statistics
    
  
  
    Your Bento account is healthy! You have 12,547 total subscribers with 95% active, and your average open rate is 42.3%.
  


---

## Managing Your Subscriber Data

Look up and understand your subscribers.


  
    Look up john.doe@example.com and tell me everything about them
  
  
    Found subscriber
    
  
  
    John Doe is an active VIP customer from Acme Corp on the Enterprise plan. He's been subscribed since January 2024 and has the newsletter and customer tags.
  


---

## Setting Up Custom Fields

Create the data structure for personalization.


  
    I need to track company name, job title, and plan type for my subscribers. Create those fields.
  
  
    I'll create those three custom fields for you.
  
  
    Created field "company_name"
    Created field "job_title"
    Created field "plan_type"
    Fields are now available for use when importing subscribers or tracking events.
  


---

## Building a Welcome Sequence

Create and populate an email sequence step by step using natural language.


  
    Show me my sequences in Bento. I want to add emails to my welcome series.
  
  
    Found 3 sequences
    
  
  
    I found your Welcome Series. I'll add a new email to it.
  
  
    Created email "Complete Your Profile" in Welcome Series
    Set delivery timing with the delayInterval and delayIntervalCount parameters, or adjust in the Bento dashboard after creation.
  


> You can reference a sequence by its name (case-insensitive) or ID. When you update sequence email HTML later, keep `{"{{ visitor.unsubscribe_url }}"}` in the content so recipients can unsubscribe.


---

## Reviewing Workflows

Check on your workflow performance and email templates.


  
    Show me my workflows and how they're performing.
  
  
    Found 2 workflows
    
  
  
    You have 2 workflows. Post-Purchase Follow-up is live with 3 email templates. Trial Expiry Reminder is still in draft with 2 emails, and you can activate it from the Bento dashboard when ready.
  


---


## Troubleshooting


  
    
  
  
    
      <h4 className="text-ink font-semibold text-lg mb-3">Testing Your Connection</h4>

      Check that the hosted server is reachable:

      
        
      

      Check your credentials by listing tools directly:

      
        
      

      For Codex, run:

      
        
      

      Then ask your AI assistant:

      
        
      

      If it works, you'll see your tags. If not, check your configuration.
    
  


---


## Best Practices


### Security

- **Never share your Secret Key** in public repositories, screenshots, or support tickets
- **Use environment variables** in CI/CD rather than hardcoding credentials
- **Rotate API keys periodically**, especially if you suspect they may have been exposed

### Performance

- **Use batch operations** when importing multiple subscribers. `bento_batch_import_subscribers` handles up to 1000 at once
- **Be specific in your prompts** to help the AI choose the right tool on the first try
- **Review broadcasts in Bento** before sending. The MCP creates drafts for safety

### Workflow Tips

- **Start with stats** to understand your account state before making changes
- **Test with a single subscriber** before bulk importing
- **Use descriptive broadcast names** so they're easy to find in the Bento dashboard
- **Leverage custom fields** for personalization. Create them once, use them everywhere

### Sequences & Workflows

- **Always include an unsubscribe URL** when updating sequence email HTML. Use `{"{{ visitor.unsubscribe_url }}"}` so recipients can always opt out
- **Reference sequences by name** for readability, or by ID for precision
- **Set delivery timing explicitly** when creating sequence emails using `delayInterval` and `delayIntervalCount`. If you leave them out, Bento uses its default delay, so check the timing in the dashboard
- **Use `bento_list_automations` with a type filter** to narrow results to just sequences or just workflows
- **Render, test, then propose.** Ask your assistant to run `bento_render_email` and `bento_send_test_email` before it approves a broadcast or proposes a flow change
- **Flow changes are proposals.** `bento_propose_workflow_change` never edits a flow. You accept or reject each change in the Flow Builder. A flow can have 20 pending proposals, and each expires after 7 days
- **Reuse segment queries.** `bento_get_segment` returns the query as a JSON string that `bento_update_segment` accepts as is. Creating segments through MCP is coming soon, so create them in Bento first. Tag rules use `cached_tag_ids` with a tag id, not a tag name
- **Upload images sparingly.** `bento_upload_image` takes PNG, JPEG, GIF, or WebP up to 1 MB, and every attempt counts toward 20 uploads per site per day, so reuse URLs you already have

---


## Quick Reference Card


### Subscriber Operations

```
"Look up [email] in Bento"
"When did [email] last open or click?"
"Import these subscribers with tag [tag]: [list]"
```

### Tag Operations

```
"What tags do I have?"
"Create a tag called [name]"
```

### Broadcast Operations

```
"Show me my broadcasts"
"Create a broadcast called [name] about [topic]"
"Update broadcast [id] to send to segment [segment]"
"Render broadcast [id] for [email] and send me a test"
```

### Sequence Operations

```
"Show me my sequences"
"Add an email to my [sequence name] sequence about [topic]"
"Update the subject on sequence email [id]"
```

### Workflow Operations

```
"Show me my workflows"
"List only my workflows"
"Show me the Onboarding workflow"
"Propose adding a [delay] after [step] in [workflow]"
"Any proposed changes on [workflow]?"
```

### Event Tracking

```
"Track [event] for [email]"
"Log a $[amount] purchase for [email]"
```

### Statistics

```
"Show me my Bento stats"
"How many subscribers do I have?"
```

---


## Alternative: Local npm Package


Most people should use the hosted server. If you need to run Bento MCP on your own machine, for example because your network blocks outside MCP connections, the `@bentonow/bento-mcp` npm package runs a local stdio server. It needs Node.js 18 or later.


> The local package is maintained separately from the hosted server, so its tool names and coverage can differ from the tools listed on this page.


Add it to any MCP client that launches local commands:


  


You can leave out the `env` block if your shell profile (`~/.zshrc` or `~/.bashrc`) exports the same three variables and your AI app inherits them:


  


To check the local server for errors, run it by hand:


  


---


## Get Help


- **Local npm package issues**: [github.com/bentonow/bento-mcp/issues](https://github.com/bentonow/bento-mcp/issues)
- **Documentation**: [docs.bentonow.com](https://docs.bentonow.com)
- **Discord**: [Join the community](https://discord.gg/ssXXFRmt5F)
- **Email Support**: support@bentonow.com

---


## Links


- [Local npm package on GitHub](https://github.com/bentonow/bento-mcp)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [Bento Node SDK](/docs/examples/nodejs)
- [API Reference](/docs/developer_guides/introduction)