Online
Bento
View markdown

Bento MCP Server

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

The Model Context Protocol (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.

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: 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, Cursor, VS Code, etc.)
  • Node.js 18 or later only if your MCP client needs a local stdio bridge
Learning Computer Streamline Icon: https://streamlinehq.comGetting 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:

CredentialDescriptionExample
Publishable KeyYour public API keypk_live_abc123...
Secret KeyYour private API key (keep this safe!)sk_live_xyz789...
Site UUIDYour unique site identifiersite_uuid_here
If you don't see API keys, click "Generate Key" to create a new set.
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.
Learning Computer Streamline Icon: https://streamlinehq.comHosted Endpoint

Bento runs a hosted MCP endpoint, so most people do not need to install or run a local MCP server.

Code
https://mcp.bentonow.com/mcp

Your MCP client sends your Bento API credentials with each request. Bento MCP does not store credentials between requests.

Use these HTTP headers when your MCP client supports a hosted HTTP endpoint:

Code

Use the hosted endpoint when your MCP client supports remote HTTP MCP servers with custom headers. If the client only supports local stdio servers, use the local npm server or a bridge such as mcp-remote.

Learning Computer Streamline Icon: https://streamlinehq.comSetup Guides by Platform

Choose your AI application below. Hosted setup is the cleanest option when your client supports it. The local npm server is still available for clients that only launch stdio MCP servers.

Learning Computer Streamline Icon: https://streamlinehq.comAvailable Tools

The MCP server provides these tools that your AI assistant can use:

Subscriber Management

"Look up john@example.com in Bento"

Look up a subscriber by email or UUID

get_subscriber

"Import these 50 subscribers with the 'webinar-attendee' tag"

Import up to 1000 subscribers at once

batch_import_subscribers
Tags

"What tags do I have in Bento?"

List all tags in your account

list_tags

"Create a tag called 'vip-customer'"

Create a new tag

create_tag
Custom Fields

"Show me my custom fields in Bento"

List all custom fields

list_fields

"Create a custom field for 'company_name'"

Create a new custom field

create_field
Event Tracking

"Track a 'completed_onboarding' event for user@example.com"

Track a custom event (can trigger automations)

track_event
Broadcasts

"Show me my recent broadcasts"

List all broadcasts/campaigns

list_broadcasts

"Create a broadcast for our spring sale announcement"

Create a new draft broadcast

create_broadcast
Automations

"What automations do I have set up?"

List all automations, filtered by sequences, workflows, or all

list_automations
Sequences

"Show me all my email sequences"

List email sequences with their email templates

list_sequences

"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

create_sequence_email

"Update the subject line on sequence email template 456"

Update a sequence email's subject or HTML content

update_sequence_email
Workflows

"Show me my workflows"

List workflows with their status and email templates

list_workflows
Email Templates

"Show me template ID 123"

Get an email template's content by ID

get_email_template

"Update template 123 with this new subject line"

Update a template's subject or content

update_email_template
Statistics

"How many subscribers do I have?"

Get overall site statistics

get_site_stats
Learning Computer Streamline Icon: https://streamlinehq.comCommon Workflows

Creating an Email Broadcast

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

›
User

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.

◆
Bento MCP

I'll create that broadcast for you.

⚡
create_broadcastrunning...
✓Created draft broadcast "Summer Sale Announcement"

The broadcast is now saved as a draft in your Bento dashboard.

Broadcasts created via MCP are always saved as drafts. You'll need to review and send them from the Bento dashboard. This is a safety feature to prevent accidental sends.

Importing Subscribers

Perfect for moving subscribers from a spreadsheet or another platform.

›
User

Import these subscribers with the tag 'newsletter-2024':
• alice@example.com (Alice Smith)
• bob@example.com (Bob Jones)
• carol@example.com (Carol Williams)

◆
Bento MCP

I'll import those 3 subscribers with the 'newsletter-2024' tag.

⚡
batch_import_subscribersrunning...
✓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.

›
User

Track a $49.99 purchase for customer@example.com. Order ID is ORD-12345, product is 'Annual Pro Plan'.

◆
Bento MCP

I'll track that purchase event.

⚡
track_event$purchaserunning...
✓Tracked event "$purchase" for customer@example.com

Purchase Event Requirements: Purchase events must include:

  • value.amount: Amount in cents (4999 for $49.99)
  • value.currency: ISO currency code (USD, EUR, etc.)
  • unique.key: A unique identifier to prevent double-counting (order ID)

The MCP server will auto-generate a unique key if you don't provide one, but using your order ID is recommended.

Checking Your Stats

Get a quick overview of your Bento account performance.

›
User

How is my Bento account doing? Give me the key stats.

⚡
get_site_statsrunning...
✓Retrieved site statistics
total_subscribers: 12,547
active_subscribers: 11,892
broadcasts_sent: 45
avg_open_rate: 42.3%
◆
Bento MCP

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.

›
User

Look up john.doe@example.com and tell me everything about them

⚡
get_subscriberjohn.doe@example.comrunning...
✓Found subscriber
status: subscribed
tags: newsletter, customer, vip
company: Acme Corp
plan: Enterprise
subscribed_at: 2024-01-15
◆
Bento MCP

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.

›
User

I need to track company name, job title, and plan type for my subscribers. Create those fields.

◆
Bento MCP

I'll create those three custom fields for you.

⚡
create_field×3running...
✓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.

›
User

Show me my sequences in Bento. I want to add emails to my welcome series.

⚡
list_sequencesrunning...
✓Found 3 sequences
1: Welcome Series (4 emails)
2: Onboarding Drip (6 emails)
3: Re-engagement (2 emails)
◆
Bento MCP

I found your Welcome Series. I'll add a new email to it.

⚡
create_sequence_emailWelcome Seriesrunning...
✓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 updating sequence email HTML later, you must include {"{{ visitor.unsubscribe_url }}"} for compliance.

Reviewing Workflows

Check on your workflow performance and email templates.

›
User

Show me my workflows and how they're performing.

⚡
list_workflowsrunning...
✓Found 2 workflows
Post-Purchase Follow-up: live, 3 emails
Trial Expiry Reminder: draft, 2 emails
◆
Bento MCP

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.

Learning Computer Streamline Icon: https://streamlinehq.comTroubleshooting

Frequently Asked Questions

Find answers to common questions or contact our support team

Missing one or more required Bento credential headers

The hosted MCP endpoint did not receive all three Bento credential headers.

  • Confirm the client sends X-Bento-Publishable-Key, X-Bento-Secret-Key, and X-Bento-Site-UUID
  • For Codex, make sure env_http_headers points to environment variable names, not literal credential values
  • For Claude Desktop with mcp-remote, confirm the env block contains all three values
  • Restart your AI application after making changes

Bento rejected the provided credentials or site UUID

Your credentials were sent, but Bento could not authenticate them.

  • Copy the publishable key, secret key, and site UUID again from Settings > API Keys
  • Make sure the publishable key and secret key belong to the same Bento account
  • Check that the site UUID matches the site you want the assistant to access
  • Regenerate your API keys if you think the secret key was exposed

MCP server not showing up

Your AI application doesn't see the Bento MCP server.

  • Verify the configuration file path is correct for your operating system
  • Check JSON syntax. A single missing comma can break the config
  • For Claude Desktop, ensure Node.js 18+ is installed because mcp-remote runs through npx
  • For Codex, run codex mcp get bento-remote and confirm the config block is in ~/.codex/config.toml
  • For local stdio setup, try running the npm server manually to check for errors
  • Restart your AI application completely

Testing Your Connection

For Codex hosted setup, run:

Code

For local stdio setup, run the server manually:

Code

Then ask your AI assistant:

Code

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

Learning Computer Streamline Icon: https://streamlinehq.comBest 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. 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 }}"} (required by the update tools for compliance)
  • Reference sequences by name for readability, or by ID for precision
  • Set delivery timing explicitly when creating sequence emails using delayInterval and delayIntervalCount. No default delay is applied
  • Use list_automations with a type filter to narrow results to just sequences or just workflows
Learning Computer Streamline Icon: https://streamlinehq.comQuick Reference Card

Subscriber Operations

Code
"Look up [email] in Bento"
"Import these subscribers with tag [tag]: [list]"

Tag Operations

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

Broadcast Operations

Code
"Show me my broadcasts"
"Create a broadcast called [name] about [topic]"

Sequence Operations

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

Workflow Operations

Code
"Show me my workflows"
"List only my workflows"

Event Tracking

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

Statistics

Code
"Show me my Bento stats"
"How many subscribers do I have?"
Learning Computer Streamline Icon: https://streamlinehq.comEnvironment Variable Approach (Advanced)

For local stdio setup, you can keep credentials in your shell profile instead of each MCP config file.

1. Add to your shell profile (~/.zshrc or ~/.bashrc):

Code

2. Use a simpler MCP config:

Code

The local npm server will automatically pick up the environment variables from your shell.

Learning Computer Streamline Icon: https://streamlinehq.comGet Help