Connect Customer.io to Claude: Manage Segments & Messaging Metrics

If your team needs to connect Customer.io to Claude to automate marketing campaigns, manage user segments, extract messaging metrics, or track custom events, you need a Model Context Protocol (MCP) server. This server acts as the critical translation layer between Claude's LLM function calling and the Customer.io REST APIs. You can either build and maintain this infrastructure entirely in-house, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL.

If your team uses ChatGPT instead, check out our companion guide on connecting Customer.io to ChatGPT or explore our broader architectural overview on connecting Customer.io to AI Agents.

Giving a Large Language Model (LLM) read and write access to a sophisticated marketing automation platform like Customer.io presents significant engineering hurdles. You must manage token lifecycles, bridge multiple disparate API domains (Track vs. App), map massive JSON schemas into standardized MCP tool definitions, and enforce strict execution guardrails. Every time Customer.io modifies an endpoint or introduces a new metric format, you have to update your server code, test the definitions, and redeploy.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Customer.io, connect it natively to Claude, and execute complex marketing workflows using natural language.

The Engineering Reality of the Customer.io API

A custom MCP server is essentially a self-hosted integration layer. While the open MCP standard provides a predictable mechanism for models to discover and execute tools, the reality of implementing it against specialized B2B APIs is painful. Customer.io is an exceptionally powerful platform, but its API surface area reflects that power through distinct architectural quirks.

If you decide to build a custom Customer.io MCP server from scratch, here are the specific integration challenges you will face:

The Split Brain: Track API vs. App API Customer.io operates on two fundamentally different API paradigms. The Track API is designed for high-throughput ingestion of events, device updates, and user identification. The App API handles configuration, campaigns, segments, and reporting. These APIs operate on different subdomains with different authentication requirements (Site ID/API Key vs. App Key). Building an MCP server requires abstracting this dual-auth complexity away from the LLM, ensuring the model can smoothly transition from querying a campaign metric (App API) to tracking a conversion event (Track API) without understanding the underlying routing.

Chronological Indexing in Version 2 Metrics Customer.io recommends using Version 2 for fetching campaign and action metrics. These endpoints return data as a series of counts where the array is ordered oldest to newest - meaning the 0-index is the oldest point in the time window. LLMs often hallucinate or misinterpret array indexing for time-series data unless the tool's JSON Schema heavily annotates exactly how to parse the array. Without dynamic, documentation-driven schema generation, the LLM will confidently give you yesterday's click-through rate when you asked for last month's.

Strictly Enforced Broadcast Payloads When triggering an API broadcast (customer_io_broadcasts_trigger), the API enforces strict structural validation. You must provide exactly one of the following fields: ids, emails, recipients, per_user_data, or data_file_url. If an LLM attempts to send both emails and per_user_data in the same payload, the API will reject it with a 400 validation error. Your MCP tool schemas must utilize JSON Schema oneOf or exactlyOne constraints to force the LLM into the correct payload shape before the network request ever fires.

Rate Limits and Standardized Headers Customer.io enforces strict rate limits across its endpoints (e.g., archived messages are limited to 100 requests per day). It is critical to note that Truto does not retry, throttle, or apply backoff on rate limit errors. When the Customer.io API returns an HTTP 429, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec. The caller - your MCP client or orchestration layer - is completely responsible for handling the retry and backoff logic.

Creating the Customer.io MCP Server

Truto eliminates the need to build a custom translation layer. It derives tool definitions dynamically from Customer.io's resource schemas and documentation. A tool only appears in the MCP server if it has a corresponding documentation entry, ensuring the LLM only interacts with curated, well-defined endpoints.

You can generate an MCP server for Customer.io using either the Truto UI or the Truto API.

Method 1: Via the Truto UI

For teams who want a zero-code setup, you can generate the MCP URL directly from the dashboard.

1. Log into your Truto account and navigate to your connected Customer.io environment.
2. Click into the specific Integrated Account you want to expose to Claude.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration. You can restrict the server to specific HTTP methods (e.g., only read operations) or specific tags (e.g., only campaigns or metrics).
6. Click Generate and copy the resulting URL (e.g., https://api.truto.one/mcp/abc123def456...).

Method 2: Via the API

For platform engineering teams embedding AI capabilities, you can dynamically provision MCP servers programmatically. This is useful when you need to spin up short-lived servers for specific user sessions.

Send a POST request to /integrated-account/:id/mcp:

curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Claude Customer.io Read-Only Server",
    "config": {
      "methods": ["read"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The API returns a secure, self-contained URL. The token in the URL encodes the integrated account identity, the method filters, and the expiration time. No additional client-side configuration is needed.

Connecting the MCP Server to Claude

Once you have the Truto MCP URL, connecting it to Claude is a straightforward process. You can configure this via the Claude application UI or through the JSON configuration file.

Method A: Via the Claude UI (Web/Desktop)

If you are using Claude Desktop or Claude Web (on supported enterprise plans), you can add the server through the interface.

1. Open Claude and navigate to Settings.
2. Locate the Integrations or Connectors section.
3. Click Add MCP Server (or Custom Connector).
4. Paste the Truto MCP URL into the Server URL field.
5. Give it a descriptive name (e.g., "Customer.io Marketing Ops").
6. Click Add. Claude will immediately perform the MCP handshake, discover the tools, and make them available in your chat context.

Method B: Via the Manual Config File (Claude Desktop)

If you prefer managing configurations as code, you can inject the server directly into Claude Desktop's configuration file.

Locate your claude_desktop_config.json file:

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the Truto MCP URL using the server-sse transport package. Because Truto MCP servers communicate over HTTP POST with JSON-RPC 2.0 (Server-Sent Events), you must use the standard MCP SSE proxy:

{
  "mcpServers": {
    "customer_io_prod": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/YOUR_SECURE_TOKEN_HERE"
      ]
    }
  }
}

Restart Claude Desktop. The application will initialize the connection, and the Customer.io tools will instantly appear in the attachment menu.

Essential Customer.io Hero Tools

Once connected, Claude has access to a massive inventory of Customer.io operations. Rather than listing all endpoints, here are the highest-leverage "hero" tools that unlock complex marketing automation workflows.

list_all_customer_io_segments

Retrieves a list of your segments. This is the foundational tool for identifying target audiences before triggering broadcasts or analyzing specific demographics.

Usage Notes: This tool does not return archived segments. LLMs use this to map natural language requests like "users who abandoned carts" to the specific segment_id required for downstream operations.

"Claude, pull a list of all active segments in Customer.io. I need to find the specific Segment ID for our 'Enterprise Trial Users - 14 Days' cohort."

customer_io_campaigns_get_journey_metrics

Returns a list of Journey Metrics for an automation campaign. These metrics show how many people triggered the automation, were messaged, and completed goals over a specified time period.

Usage Notes: Requires a campaign_id, start, and end timestamp. This tool gives Claude full visibility into funnel performance, allowing it to generate executive summaries on campaign health.

"Fetch the journey metrics for campaign ID 4591 for the last 30 days. Calculate the drop-off rate between people who triggered the automation and people who actually received a message, then summarize the findings."

customer_io_broadcasts_trigger

Sends an API-triggered broadcast to a specific audience, optionally injecting data to populate liquid placeholders in the message.

Usage Notes: The payload is extremely strict. Claude must supply the broadcast_id and exactly one audience definition array (ids, emails, recipients, etc.). This is a powerful write operation; ensure your MCP token config is set properly if you want to restrict send capabilities.

"Trigger the 'Q3 Feature Announcement' broadcast (ID 8821). Send it exclusively to the emails test1@acme.com and test2@acme.com. Inject the custom liquid variable 'account_tier' as 'Premium' for both recipients."

customer_io_track_events_track

Sends an event associated with a specific person. Represents actions your customers have performed in your application (e.g., page, screen, or custom event).

Usage Notes: This hits the Customer.io Track API. It requires an identifier (like cio_id or email) and an event name. Claude can use this to backfill behavioral data or log actions based on external triggers.

"Log a custom event for the user with email ceo@starkindustries.com. The event name should be 'viewed_enterprise_pricing', and include a timestamp of today."

customer_io_customers_get_attributes

Returns a comprehensive list of attributes for a specific customer profile. Attributes are the core data points used to construct segments or populate liquid merge fields.

Usage Notes: Requires a customer_id. The LLM uses this tool to audit a user's state, check their subscription preferences, or verify data integrity before escalating support tickets.

"Look up the profile attributes for customer ID 99281. Tell me what their current 'LTV' attribute is set to, and check if they have the 'churn_risk' boolean flagged."

create_a_customer_io_segment

Creates a manual segment with a name and a description.

Usage Notes: This creates an empty manual segment. It cannot be used to create data-driven or snapshot segments. Once created, Claude can use customer_io_track_segments_add_customers to populate it.

"Create a new manual segment in Customer.io named 'VIP Conference Attendees 2026' with the description 'Manually uploaded list of high-value prospects from the keynote'."

To view the complete inventory of available tools, schemas, and required parameters, visit the Customer.io integration page.

Workflows in Action

Connecting Claude to Customer.io transforms natural language requests into complex, multi-step API orchestration. Here are two real-world workflows that demonstrate the power of LLM function calling via MCP.

Scenario 1: Executive Campaign Reporting & Triage

A Director of Marketing wants a diagnostic breakdown of a recent onboarding campaign without having to log into the Customer.io dashboard, export CSVs, and build a spreadsheet.

"Claude, find our 'Self-Serve Onboarding' campaign. Pull the journey metrics and the specific link click metrics for the past 14 days. If the click-through rate on the second action step is below 5%, find out which users are getting stuck."

How the agent executes this:

1. Discovery: Claude calls list_all_customer_io_campaigns to search for the automation named "Self-Serve Onboarding" and retrieves its campaign_id.
2. High-Level Metrics: Claude calls customer_io_campaigns_get_journey_metrics using the ID and a calculated date range to assess overall funnel volume (triggered vs. messaged).
3. Granular Analysis: Claude calls list_all_customer_io_campaign_actions to get the specific action_id for the second step in the flow.
4. Link Metrics: It then calls customer_io_campaign_actions_get_link_metrics for that specific action to retrieve the CTR.
5. Resolution: If the CTR is below the threshold, Claude formats a structured markdown report detailing the drop-off points, utilizing the time-series arrays correctly because of the embedded schema definitions.

sequenceDiagram
    participant User
    participant Claude as Claude Desktop
    participant MCP as Truto MCP Server
    participant Upstream as Customer.io API

    User->>Claude: "Analyze Self-Serve Onboarding campaign..."
    Claude->>MCP: Call list_all_customer_io_campaigns
    MCP->>Upstream: GET /v1/campaigns
    Upstream-->>MCP: Return campaign list
    MCP-->>Claude: Return campaign_id: 1045
    
    Claude->>MCP: Call campaigns_get_journey_metrics (id: 1045)
    MCP->>Upstream: GET /v1/campaigns/1045/journey_metrics
    Upstream-->>MCP: Return funnel metrics
    MCP-->>Claude: Return journey data

    Claude->>MCP: Call list_all_campaign_actions (id: 1045)
    MCP->>Upstream: GET /v1/campaigns/1045/actions
    Upstream-->>MCP: Return actions list
    MCP-->>Claude: Return action_id: 992

    Claude->>MCP: Call actions_get_link_metrics (id: 1045, action: 992)
    MCP->>Upstream: GET /v1/campaigns/1045/actions/992/metrics/links
    Upstream-->>MCP: Return click data
    MCP-->>Claude: Return CTR metrics
    Claude-->>User: Present diagnostic report

Scenario 2: Dynamic Segment Generation and Broadcast Execution

A Revenue Operations engineer wants to run a targeted intervention for high-value users who recently hit an error state in the product.

"Claude, create a new manual segment called 'Q4 Outage Affected VIPs'. Look up the profile for user ID 'ent_8841', check if their 'LTV' attribute is over $10,000. If it is, add them to this new segment, and then trigger the 'Outage Apology' broadcast to that segment."

How the agent executes this:

1. Creation: Claude calls create_a_customer_io_segment and stores the returned segment_id.
2. Attribute Verification: Claude calls customer_io_customers_get_attributes passing ent_8841. It parses the response to verify the LTV value.
3. Population: Assuming the condition is met, Claude uses the Track API tool customer_io_track_segments_add_customers to push ent_8841 into the newly created segment.
4. Discovery: It calls list_all_customer_io_broadcasts to find the ID for the "Outage Apology" broadcast.
5. Execution: Claude calls customer_io_broadcasts_trigger, passing the broadcast ID and using the segment_id inside the recipients payload object to execute the send.

Security and Access Control

When granting AI agents access to your marketing operations and user data, security cannot be an afterthought. Truto's MCP architecture provides strict, hardware-enforced boundaries for LLM tool execution.

• Method Filtering (config.methods): Restrict Claude's capabilities at the server level. You can generate an MCP URL limited exclusively to read operations (e.g., fetching metrics and listing campaigns) entirely blocking write access (e.g., triggering broadcasts or deleting users).
• Tag Filtering (config.tags): Scope the server to specific functional areas. For example, you can expose only endpoints tagged with metrics or segments, hiding administrative settings and Track API endpoints.
• Secondary Authentication (require_api_token_auth): For sensitive deployments, having the MCP URL is not enough. Enabling this flag forces the MCP client to also pass a valid Truto API token in the Authorization header, ensuring only authenticated personnel can invoke tools.
• Time-to-Live (expires_at): Generate ephemeral MCP servers for temporary troubleshooting. Set an absolute ISO datetime, and the server's access token will be automatically wiped from the distributed KV store the millisecond it expires.

Automate Marketing Operations with Truto

Building a reliable, schema-aware integration layer between Claude and Customer.io requires months of mapping, token management, and edge-case handling. The dual nature of Customer.io's Track and App APIs only compounds this complexity.

Truto's dynamic, documentation-driven MCP generation solves this instantly. By deriving tools directly from normalized resource definitions, you ensure your AI agents have secure, accurate, and curated access to your marketing data without writing a single line of integration code.

Ready to give your AI agents secure, authenticated access to Customer.io and over 100 other B2B SaaS APIs? Let's talk about managed MCP infrastructure.