How to integrate Customerio MCP with LangChain

Connect LangChain to Customerio MCP. List all segments in your workspace, get delivery metrics for last week's emails, and more using natural language, with authentication handled for you.

Customerio logoCustomerio
Api Key

Customer.io is a customer engagement platform for targeted messaging across email, SMS, and push. Easily automate, segment, and track communications with your audience.

39 Tools

Introduction

This guide walks you through connecting Customerio to LangChain using the Composio tool router. By the end, you'll have a working Customerio agent that can identify people, track events and page views, trigger broadcasts, review segments and metrics, and suppress or unsubscribe customers through natural language commands.

This guide will help you understand how to give your LangChain agent real control over a Customerio account through Composio's Customerio MCP server.

Before we dive in, let's take a quick look at the key ideas and tools involved.

For exact tool slugs and parameter tables, see the tool catalog in the Composio docs.

Also integrate Customerio with

TL;DR

Here's what you'll learn:
  • Get and set up your OpenAI and Composio API keys
  • Connect your Customerio project to Composio
  • Create a Tool Router MCP session for Customerio
  • Initialize an MCP client and retrieve Customerio tools
  • Build a LangChain agent that can interact with Customerio
  • Set up an interactive chat interface for testing

What is LangChain?

LangChain is a framework for developing applications powered by language models. It provides tools and abstractions for building agents that can reason, use tools, and maintain conversation context.

Key features include:

  • Agent Framework: Build agents that can use tools and make decisions
  • MCP Integration: Connect to external services through Model Context Protocol adapters
  • Memory Management: Maintain conversation history across interactions
  • Multi-Provider Support: Works with OpenAI, Anthropic, and other LLM providers

What is the Customerio MCP server, and what's possible with it?

The Customerio MCP server is an implementation of the Model Context Protocol that connects your AI agent and assistants like Claude, Cursor, etc directly to your Customer.io account. It provides structured and secure access to your customer engagement workspace, allowing your agent to send targeted communications, manage segments, retrieve messaging analytics, and automate customer data management on your behalf.

  • Targeted message analytics and tracking: Retrieve detailed lists of messages sent, including delivery metrics, to monitor campaign performance and engagement.
  • Segment discovery and membership management: Let your agent fetch all segments, get details for a specific segment, and list all customers in a segment for precise audience targeting.
  • Integration and webhook management: Have your agent list and review all integrations and webhooks in your workspace to streamline system connectivity and reporting.
  • Customer profile suppression: Direct your agent to permanently suppress (delete and block) customer profiles, ensuring compliance and data privacy.
  • Collection metadata retrieval: Retrieve up-to-date details for all collections in your workspace, keeping your AI-powered workflows and automations in sync with your data sources.

What is the Composio tool router, and how does it fit here?

What is Composio SDK?

Composio's Composio SDK helps agents find the right tools for a task at runtime. You can plug in multiple toolkits (like Gmail, HubSpot, and GitHub), and the agent will identify the relevant app and action to complete multi-step workflows. This can reduce token usage and improve the reliability of tool calls. Read more here: Getting started with Composio SDK

The tool router generates a secure MCP URL that your agents can access to perform actions.

How the Composio SDK works

The Composio SDK follows a three-phase workflow:

  1. Discovery: Searches for tools matching your task and returns relevant toolkits with their details.
  2. Authentication: Checks for active connections. If missing, creates an auth config and returns a connection URL via Auth Link.
  3. Execution: Executes the action using the authenticated connection.

Step-by-step Guide

Step by step10 STEPS
1

Prerequisites

Before starting this tutorial, make sure you have:
  • Python 3.10 or higher installed on your system
  • A Composio account with an API key
  • An OpenAI API key
  • Basic familiarity with Python and async programming
2

Getting API Keys for OpenAI and Composio

OpenAI API Key
  • Go to the OpenAI dashboard and create an API key. You'll need credits to use the models, or you can connect to another model provider.
  • Keep the API key safe.
Composio API Key
  • Log in to the Composio dashboard.
  • Navigate to your API settings and generate a new API key.
  • Store this key securely as you'll need it for authentication.
3

Install dependencies

npm install @composio/langchain @langchain/core @langchain/openai @langchain/mcp-adapters dotenv

Install the required packages for LangChain with MCP support.

What's happening:

  • @composio/langchain provides Composio integration for LangChain
  • @langchain/mcp-adapters enables MCP client connections
  • @langchain/core is the core agent framework
  • dotenv/config loads environment variables
4

Set up environment variables

bash
COMPOSIO_API_KEY=your_composio_api_key_here
COMPOSIO_USER_ID=your_composio_user_id_here
OPENAI_API_KEY=your_openai_api_key_here

Create a .env file in your project root.

What's happening:

  • COMPOSIO_API_KEY authenticates your requests to Composio's API
  • COMPOSIO_USER_ID identifies the user for session management
  • OPENAI_API_KEY enables access to OpenAI's language models
5

Import dependencies

import { Composio } from '@composio/core';
import { LangchainProvider } from '@composio/langchain';
import { MultiServerMCPClient } from "@langchain/mcp-adapters";
import { createAgent } from "langchain";
import * as readline from 'readline';
import 'dotenv/config';

dotenv.config();
What's happening:
  • We're importing LangChain's MCP adapter and Composio SDK
  • The dotenv/config import loads environment variables from your .env file
  • This setup prepares the foundation for connecting LangChain with Customerio functionality through MCP
6

Initialize Composio client

const composioApiKey = process.env.COMPOSIO_API_KEY;
const userId = process.env.COMPOSIO_USER_ID;

if (!composioApiKey) throw new Error('COMPOSIO_API_KEY is not set');
if (!userId) throw new Error('COMPOSIO_USER_ID is not set');

async function main() {
    const composio = new Composio({
        apiKey: composioApiKey as string,
        provider: new LangchainProvider()
    });
What's happening:
  • We're loading the COMPOSIO_API_KEY from environment variables and validating it exists
  • Creating a Composio instance that will manage our connection to Customerio tools
  • Validating that COMPOSIO_USER_ID is also set before proceeding
7

Create a Tool Router session

const session = await composio.create(
    userId as string,
    {
        toolkits: ['customerio']
    }
);

const url = session.mcp.url;
What's happening:
  • We're creating a Tool Router session that gives your agent access to Customerio tools
  • The create method takes the user ID and specifies which toolkits should be available
  • The returned session.mcp.url is the MCP server URL that your agent will use
  • This approach allows the agent to dynamically load and use Customerio tools as needed
8

Configure the agent with the MCP URL

const client = new MultiServerMCPClient({
    "customerio-agent": {
        transport: "http",
        url: url,
        headers: {
            "x-api-key": process.env.COMPOSIO_API_KEY
        }
    }
});

const tools = await client.getTools();

const agent = createAgent({ model: "gpt-5", tools });
What's happening:
  • We're creating a MultiServerMCPClient that connects to our Customerio MCP server via HTTP
  • The client is configured with a name and the URL from our Tool Router session
  • getTools() retrieves all available Customerio tools that the agent can use
  • We're creating a LangChain agent using the GPT-5 model
9

Set up interactive chat interface

let conversationHistory: any[] = [];

console.log("Chat started! Type 'exit' or 'quit' to end the conversation.\n");
console.log("Ask any Customerio related question or task to the agent.\n");

const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout,
    prompt: 'You: '
});

rl.prompt();

rl.on('line', async (userInput: string) => {
    const trimmedInput = userInput.trim();

    if (['exit', 'quit', 'bye'].includes(trimmedInput.toLowerCase())) {
        console.log("\nGoodbye!");
        rl.close();
        process.exit(0);
    }

    if (!trimmedInput) {
        rl.prompt();
        return;
    }

    conversationHistory.push({ role: "user", content: trimmedInput });
    console.log("\nAgent is thinking...\n");

    const response = await agent.invoke({ messages: conversationHistory });
    conversationHistory = response.messages;

    const finalResponse = response.messages[response.messages.length - 1]?.content;
    console.log(`Agent: ${finalResponse}\n`);
        
        rl.prompt();
    });

    rl.on('close', () => {
        console.log('\n👋 Session ended.');
        process.exit(0);
    });
What's happening:
  • We initialize an empty conversationHistory list to maintain context across interactions
  • A readline interface is used to continuously accept user input from the command line
  • When a user types a message, it's added to the conversation history and sent to the agent
  • The agent processes the request using the invoke() method with the full conversation history
  • Users can type 'exit', 'quit', or 'bye' to end the chat session gracefully
10

Run the application

main().catch((err) => {
    console.error('Fatal error:', err);
    process.exit(1);
});
What's happening:
  • We call the main() function to start the application

Complete Code

Here's the complete code to get you started with Customerio and LangChain:

import { Composio } from '@composio/core';
import { LangchainProvider } from '@composio/langchain';
import { MultiServerMCPClient } from "@langchain/mcp-adapters";  
import { createAgent } from "langchain";
import * as readline from 'readline';
import 'dotenv/config';

const composioApiKey = process.env.COMPOSIO_API_KEY;
const userId = process.env.COMPOSIO_USER_ID;

if (!composioApiKey) throw new Error('COMPOSIO_API_KEY is not set');
if (!userId) throw new Error('COMPOSIO_USER_ID is not set');

async function main() {
    const composio = new Composio({
        apiKey: composioApiKey as string,
        provider: new LangchainProvider()
    });

    const session = await composio.create(
        userId as string,
        {
            toolkits: ['customerio']
        }
    );

    const url = session.mcp.url;
    
    const client = new MultiServerMCPClient({
        "customerio-agent": {
            transport: "http",
            url: url,
            headers: {
                "x-api-key": process.env.COMPOSIO_API_KEY
            }
        }
    });
    
    const tools = await client.getTools();
  
    const agent = createAgent({ model: "gpt-5", tools });
    
    let conversationHistory: any[] = [];
    
    console.log("Chat started! Type 'exit' or 'quit' to end the conversation.\n");
    console.log("Ask any Customerio related question or task to the agent.\n");
    
    const rl = readline.createInterface({
        input: process.stdin,
        output: process.stdout,
        prompt: 'You: '
    });

    rl.prompt();

    rl.on('line', async (userInput: string) => {
        const trimmedInput = userInput.trim();
        
        if (['exit', 'quit', 'bye'].includes(trimmedInput.toLowerCase())) {
            console.log("\nGoodbye!");
            rl.close();
            process.exit(0);
        }
        
        if (!trimmedInput) {
            rl.prompt();
            return;
        }
        
        conversationHistory.push({ role: "user", content: trimmedInput });
        console.log("\nAgent is thinking...\n");
        
        const response = await agent.invoke({ messages: conversationHistory });
        conversationHistory = response.messages;
        
        const finalResponse = response.messages[response.messages.length - 1]?.content;
        console.log(`Agent: ${finalResponse}\n`);
        
        rl.prompt();
    });

    rl.on('close', () => {
        console.log('\nSession ended.');
        process.exit(0);
    });
}

main().catch((err) => {
    console.error('Fatal error:', err);
    process.exit(1);
});

Conclusion

You've successfully built a LangChain agent that can interact with Customerio through Composio's Tool Router.

Key features of this implementation:

  • Dynamic tool loading through Composio's Tool Router
  • Conversation history maintenance for context-aware responses
  • Async Python provides clean, efficient execution of agent workflows
You can extend this further by adding error handling, implementing specific business logic, or integrating additional Composio toolkits to create multi-app workflows.
TOOLS

Supported Tools

Every Customerio action and event your agent gets out of the box.

Add Person to Group

Add a person to a Customer.io group to establish a relationship with an object such as a company, account, or project.

Author, Version, and Publish Email

Update and version a linked Design Studio email, then publish it.

Create Profile Alias

Create an alias to merge Customer.io profiles for a person with multiple identifiers.

Create Segment

Create an empty manual segment in Customer.io.

Suppress Customer Profile

Suppress a customer profile to permanently delete it and prevent re-adding with the same identifier.

Find Customers by Email

Return Customer.io profiles whose email exactly matches the provided address.

Get Account Region

Return the region and Track API URL for the connected Customer.io account.

Get Customer Attributes

Return one Customer.io profile's attributes and devices.

Get Integrations

Retrieve a list of integrations in your workspace to discover configured integrations.

Get Messages

Tool to retrieve a list of messages sent from your workspace.

Get Newsletter Content Metrics

Retrieve engagement metrics for a Customer.io one-time send variant.

Get Newsletter Metrics

Retrieve aggregate engagement metrics for a Customer.io one-time send.

Get Segment Customer Count

Return the current number of profiles in a Customer.io segment.

Get Segment Details

Tool to retrieve details of a specific segment.

Get Segment Membership

Tool to retrieve people in a specific segment.

Get Segments

Tool to retrieve a list of segments in your workspace.

Get Transactional Metrics

Return aggregate engagement metrics for a transactional message template.

Get Trigger

Retrieves details about a specific API-triggered broadcast, including trigger ID, campaign ID, creation timestamp, recipient filter criteria, and personalization data.

Get Broadcast Triggers

Retrieve all API trigger instances for a specific broadcast/campaign.

Get Customer.io Workspace Webhooks

Retrieves all reporting webhook configurations from the Customer.io workspace.

Identify Person

Identify a person in Customer.io and assign traits, creating a profile or updating an existing one.

List Activities

Return recent workspace activity-log entries with optional filters.

List Campaigns

Return Customer.io automations and their metadata.

List Collections

Tool to list all Collections metadata.

List Customer Attributes

Return attributes and devices for up to 100 Customer.io profiles.

List IP Addresses

Tool to retrieve the list of IP addresses used by Customer.io for sending messages.

List Newsletters

Tool to list all newsletters.

List Snippets

Tool to list all snippets in your workspace.

List Transactional Contents

Return every language and content variant of a transactional template.

List Transactional Messages

Lists all transactional message templates in your Customer.io workspace.

List Workspaces

List Customer.io workspaces and their cached usage counts.

Preview Email

Evaluate a Design Studio email against sample Liquid data without sending.

Search Customers

Search Customer.io profiles using an audience filter.

Send Batch CDP Calls

Send multiple CDP calls (identify, track, page, screen, group, alias) in a single batch request.

Track Event

Tool to send an event associated with a person in Customer.io.

Track Page View

Track page views for website visitors through the Customer.io CDP API, providing a user ID or anonymous ID and optional page properties.

Track Screen View

Track mobile screen views in Customer.io for analytics and user journey tracking.

Trigger Broadcast

Manually trigger a Customer.io broadcast/campaign to send messages to a defined audience.

Unsubscribe from Delivery

Tool to handle custom unsubscribe requests for email deliveries in Customer.io.

FAQ

Frequently asked questions

Start with Customerio.It takes 30 seconds.

Managed auth, hosted MCP servers, and every Customerio tool your agent needs.Free to start.

Start building