Create a new Klaviyo email or SMS campaign. Requires a name, channel (email/sms), and audiences with included list IDs. Use list_lists to find valid list IDs.
Get a Klaviyo campaign by ID. Returns campaign details including name, status, and channel. Use list_campaigns to find valid campaign IDs.
Update a Klaviyo campaign's name or audiences. Only provided fields are updated. Use get_campaign to verify current state first.
Delete a Klaviyo campaign. Only draft campaigns can be deleted. Use list_campaigns to find valid campaign IDs.
List Klaviyo campaigns, optionally filtered by channel (email or sms). Returns campaign IDs, names, statuses, and channels.
Send a Klaviyo campaign immediately. The campaign must be in a sendable state (not draft). Use get_campaign to check status first.
Create a new Klaviyo event (e.g. Placed Order, Viewed Product) for a profile. Events are used to track actions and trigger flows. Use list_profiles to find profile IDs.
Get a Klaviyo event by ID. Returns event details including metric, profile, properties, and timestamp.
List Klaviyo events with optional filters by metric ID or profile ID, and pagination. Use listmetrics to find metric IDs. Use cursor from pageinfo for next page.
Get a Klaviyo flow by ID. Returns flow details including name and status (live, draft, manual). Use list_flows to find valid flow IDs.
List all Klaviyo flows. Flows are automated sequences triggered by events or conditions. Returns flow IDs, names, and statuses.
Update a Klaviyo flow's status to live, draft, or manual. Use get_flow to check current status first.
Get all actions in a Klaviyo flow. Returns action IDs, types, and statuses for a given flow. Use list_flows to find valid flow IDs.
Create a new Klaviyo list. Lists are used to organize profiles for targeting in campaigns and flows.
Get a Klaviyo list by ID. Returns list details including name and timestamps.
Update a Klaviyo list name. Use getlist or listlists to find valid list IDs.
Delete a Klaviyo list. This does not delete the profiles in the list. Use list_lists to find valid list IDs.
List all Klaviyo lists. Returns list IDs and names for targeting in campaigns.
Get profiles in a Klaviyo list with pagination. Returns up to 100 profiles per page. Use cursor from page_info for next page.
Add one or more profiles to a Klaviyo list. Use create_profile to create profiles first, then use their IDs here.
Remove one or more profiles from a Klaviyo list. This does not delete the profiles, only removes the list membership.
Get a Klaviyo metric by ID. Metrics represent event types like 'Placed Order' or 'Viewed Product'. Use list_metrics to find valid metric IDs.
List all Klaviyo metrics. Metrics represent event types that are tracked (e.g. 'Placed Order', 'Opened Email'). Returns metric IDs and names.
Query aggregate data for a Klaviyo metric (e.g. count, sum, unique over time). Use list_metrics to find metric IDs. Specify measurements like 'count' or 'sum' and optional time interval.
Create a new Klaviyo profile with email, phone number, name, and custom properties. At least one of email or phone_number is required.
Get a Klaviyo profile by ID. Returns profile details including email, phone, name, and custom properties.
Update a Klaviyo profile's email, phone number, name, or custom properties. Only provided fields are updated.
List Klaviyo profiles with pagination. Returns up to 100 profiles per page. Use cursor from page_info for next page.
Get all lists a Klaviyo profile belongs to. Returns list IDs and names.
Get all segments a Klaviyo profile belongs to. Returns segment IDs and names.
Get a Klaviyo segment by ID. Segments are dynamic groups of profiles based on conditions. Use list_segments to find valid segment IDs.
List all Klaviyo segments. Segments are dynamic groups of profiles that update automatically based on conditions.
Get profiles in a Klaviyo segment with pagination. Returns up to 100 profiles per page. Use cursor from page_info for next page.
Create a new Klaviyo tag within a tag group. Tags are used to organize campaigns, flows, lists, and segments. Use listtaggroups to find valid tag group IDs.
Get a Klaviyo tag by ID. Use list_tags to find valid tag IDs.
Update a Klaviyo tag's name. Use list_tags to find valid tag IDs.
Delete a Klaviyo tag. This cannot be undone. Use list_tags to find valid tag IDs.
List all Klaviyo tags. Tags are used to organize and categorize campaigns, flows, lists, and segments.
Create a new Klaviyo tag group. Tag groups organize related tags. Set exclusive=true if tags in the group should be mutually exclusive.
List all Klaviyo tag groups. Tag groups organize related tags together. Returns group IDs, names, and exclusivity settings.
Create a new Klaviyo email template with a name and optional HTML/text content. Templates can be used in campaigns and flows.
Get a Klaviyo template by ID. Returns template details including name, HTML, and text content. Use list_templates to find valid template IDs.
Update a Klaviyo template's name, HTML, or text content. Only provided fields are updated. Use get_template to check current content.
Delete a Klaviyo template. This cannot be undone. Use list_templates to find valid template IDs.
List all Klaviyo email templates. Returns template IDs, names, and content for use in campaigns and flows.
Render a Klaviyo template with context variables. Returns the rendered HTML and text content with variables replaced.
Clone a Klaviyo template with a new name. Creates an exact copy of the template. Use list_templates to find valid template IDs.
Validate Klaviyo credentials by fetching account info. Returns {success, message}.
In an mcp.json file, add the configuration below, and restart Cursor.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5 "headers": {
6 "Authorization": "Bearer yMt*****"
7 }
8 }
9 }
10}
11Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.
Make sure Claude is using the Node v20+.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "command": "npx",
5 "args": [
6 "-y",
7 "mcp-remote@latest",
8 "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9 "--header",
10 "Authorization: Bearer ${AUTH_TOKEN}"
11 ],
12 "env": {
13 "AUTH_TOKEN": "yMt*****"
14 }
15 }
16 }
17}Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "command": "npx",
5 "args": [
6 "-y",
7 "mcp-remote@latest",
8 "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9 "--header",
10 "Authorization: Bearer ${AUTH_TOKEN}"
11 ],
12 "env": {
13 "AUTH_TOKEN": "<ah-production-access-key>"
14 }
15 }
16 }
17 }In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".
You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.
Learn more in the official documentation ↗
1{
2 "inputs": [
3 {
4 "type": "promptString",
5 "id": "agent-handler-auth",
6 "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7 "password": true
8 }
9 ],
10 "servers": {
11 "agent-handler": {
12 "type": "stdio",
13 "command": "npx",
14 "args": [
15 "-y",
16 "mcp-remote@latest",
17 "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18 "--header",
19 "Authorization: Bearer ${input:agent-handler-auth}"
20 ]
21 }
22 }
23}It's an MCP server that wires your agents into Klaviyo's customer engagement platform via tools. Your agents can invoke these tools to create and send campaigns, manage customer profiles, add contacts to lists, query performance metrics, and more.
Klaviyo offers an official MCP server, but you can also use one from a third-party platform, like Merge Agent Handler.
The use cases naturally depend on the agent you've built, but here are a few common ones:
Here are some of the most commonly used tools:
create_campaign: creates a new email or SMS campaign in Klaviyo with a specified name, audience, and send strategy. Use this when an agent needs to build a campaign programmatically in response to a scheduled event or business triggersend_campaign: triggers the send of a created campaign to its configured audience. Call this when an agent has confirmed all campaign details are ready and needs to initiate delivery without manual interventioncreate_profile: adds a new contact to Klaviyo with fields like email, phone, and custom properties. Use this when an agent is ingesting new customer data from an external system like a CRM, e-commerce platform, or form submissionupdate_profile: modifies an existing profile's attributes, including custom properties, consent status, or lifecycle stage. Good for workflows that sync behavioral signals or enrichment data from other tools back into Klaviyoadd_profiles_to_list: adds one or more profiles to a Klaviyo list, making them eligible for campaigns and flows targeting that list. Helpful when an agent is segmenting contacts based on actions taken in another systemquery_metric_aggregates: runs an aggregated query against a Klaviyo metric, returning totals and breakdowns over a specified time range. Use this when an agent is compiling performance reports or evaluating campaign effectiveness across a date windowKlaviyo has its own official MCP server, but running it through Merge Agent Handler makes sense for teams that need stricter controls:
You can take the following steps:
1. Create or log into your Merge Agent Handler account and navigate to Tool Packs (collections of connector tools scoped to a specific use case).
2. Create a new Tool Pack, then find and enable the Klaviyo connector. Match the tools to your workflow: analytics tools like query_metric_aggregates and list_campaigns work for reporting agents, while create_profile, add_profiles_to_list, and send_campaign are needed for agents that take action on customer data.
3. Add a Registered User inside the Tool Pack. This is the identity context under which your agent operates. Merge generates a unique MCP URL scoped to this user once it's created.
4. From the Registered User detail page, authenticate Klaviyo by completing the OAuth flow or entering your API key. Merge stores and manages the credentials going forward.
5. Copy the MCP URL from the Tool Pack detail page and generate an API key from Settings. You'll need both to connect your agent.
6. Add the MCP server to your agent or IDE using the MCP URL and API key. Your Klaviyo tools are now accessible through that endpoint.
Whether you're an engineer experimenting with agents or a product manager looking to add tools, you can get started for free now
