> This page is part of the [Customer.io documentation](https://docs.customer.io). For the complete index, see [llms.txt](https://docs.customer.io/llms.txt).

# Get started with the Customer.io MCP server

 Recently updated

We’ve updated our MCP server with write operations and a new tool architecture. Your existing sessions and natural language prompts continue to work. If you have hardcoded tool references in custom GPTs, Claude Projects, or scripts, see our [migration guide](/ai/mcp/mcp-migration/) for details.

## How it works[](#how-it-works)

Customer.io MCP connects your Customer.io account to AI tools that support the [Model Context Protocol](https://modelcontextprotocol.io/). With the MCP server, you can do just about anything you can do in Customer.io via your AI tool of choice—read workspace data, create and manage campaigns, send newsletters, work with segments, and more—all through natural language prompts.

The way you set up your MCP client depends on the tool you use. See our instructions for [ChatGPT](/ai/mcp/chatgpt/), [Claude](/ai/mcp/claude/), and [Cursor](/ai/mcp/ide/) for details.

 Make sure you trust your AI tools

Customer.io MCP works with *your* AI provider of choice and includes tools that return information about people in your workspace. While our LLM subprocessors don’t store this data, the AI providers you use might. Make sure that you use AI tools that are approved by your organization to ensure the safety of your—and your customers’—data.

 Using Claude Code or another terminal-based agent?

If your AI tool runs in a terminal, our [Customer.io CLI](/ai/cli/get-started/) is usually a better fit than MCP. The CLI gives your agent direct command-line access to the full API surface—no MCP setup required.

## What can Customer.io MCP do?[](#what-can-customerio-mcp-do)

Customer.io MCP gives your AI tools access to your workspace through a set of tools. You don’t need to tell your AI tool which tools to use—just describe what you want, and it picks the right ones.

The current version of Customer.io MCP gives your AI tool access to the full Journeys UI API and CDP Data Pipelines API. Your AI tool can discover endpoints, read data, and perform write operations—all through natural language prompts.

The tools available to your AI tool are:

Tool

What it does

`cio_prime`

Loads the AI-ready reference for the Customer.io API. Your AI tool should call this at the start of a task.

`cio_schema`

Discovers API endpoints—list resources, find endpoints, and inspect parameters before making calls.

`cio_api`

Makes authenticated API requests. Read-only by default; writes are opt-in. Supports filtering, pagination, and dry-run previews.

`cio_skills_list`

Lists available agent skills—task-specific instructions for multi-step operations like creating campaigns.

`cio_skills_read`

Reads the full content of a specific skill so the AI tool can follow step-by-step workflows.

`cio_auth_status`

Shows the current authentication state, including which workspaces the token can access.

**Writing data to Customer.io.** By default, `cio_api` only makes GET requests. Your AI tool has to explicitly opt in to a write on each call, so read requests (\*

*   **Strict body validation.** Requests with unknown fields in the body return a `422` error rather than silently dropping them. This catches typos and stale field names before they cause confusing failures.
*   **Structured JSON errors.** Tool errors come back as JSON, not plain text. If you’ve built workflows that parse the older text-format errors, you’ll need to update them.

**The MCP includes skills to help your AI tool understand Customer.io.** Some of the tools above (`cio_skills_list`, `cio_skills_read`) give your AI access to a Customer.io-maintained library of task-specific instructions. Your AI tool fetches the right skill on its own when it recognizes a task; you don’t need to invoke them by name.

So when you give your AI tool a task, it’ll read skills to understand how to accomplish the task in Customer.io, look up schemas to perform the task, and then do the work.

You don’t need to tell your AI tool which skills to use—it’ll figure it out on its own when it recognizes a task. But you can ask your AI to do things like:

*   *“List all active campaigns in my workspace.”*
*   *“Create a segment of users who signed up in the last 7 days.”*
*   *“Show me the delivery metrics for my onboarding campaign.”*
*   *“Draft a welcome email in Design Studio.”*
*   *“Set up a new CDP source for my React Native app.”*

## Enable Customer.io MCP for your account[](#enable-customerio-mcp-for-your-account)

You must be an account admin to enable Customer.io MCP for your account. After you enable it, you and other users can set up clients—see [ChatGPT](/ai/mcp/chatgpt/), [Claude](/ai/mcp/claude/), or [Cursor and other IDEs](/ai/mcp/ide/).

1.  Go to [**Settings** > **Privacy, Data, & AI**](https://fly.customer.io/settings/privacy/).
    
2.  Turn on **Customer.io MCP**. If it isn’t already enabled, you’ll also need to turn on **Customer.io AI**. You must enable both **Customer.io AI** and **Customer.io MCP** for team members to use Customer.io MCP.
    
    [![The Privacy & Data Settings page showing the Customer.io MCP setting enabled](https://docs.customer.io/images/privacy-page-mcp-2.png)](#4b2a53357c771b595969720f9eae4338-lightbox)
    

Now you’re ready to set up your MCP client—see [ChatGPT](/ai/mcp/chatgpt/), [Claude](/ai/mcp/claude/), or [Cursor and other IDEs](/ai/mcp/ide/) for help.

 Enabling *Customer.io AI* also enables a set of AI features in your account across all team members

These features include the ability to translate messages with AI, analyze email content, build segments from written descriptions, and more. [Learn more about our AI features](/ai/cio-with-llms/#our-current-ai-tools).

### Who can do what[](#who-can-do-what)

*   **Account admins** can enable or disable Customer.io MCP for the account. Other users can’t change this setting.
*   **Any user** in an account where MCP is enabled can connect their own MCP client. Each user authenticates with their own Customer.io login, and connections respect that user’s role and permissions—your AI tool can only do things you can do.
*   **Each user manages their own sessions.** Account admins can’t view or revoke MCP sessions for other users. To revoke a session, the user who created it has to do it from their own personal settings.

### What happens when you disable MCP[](#what-happens-when-you-disable-mcp)

Turning off the **Customer.io MCP** toggle stops MCP requests immediately. Customer.io checks the toggle on every API call, so existing sessions can no longer use any MCP tools. Re-enabling the toggle restores access for those same sessions—we don’t delete the underlying OAuth tokens, so users don’t need to reconnect.

If you want to revoke a specific connection permanently, the user who created it has to revoke their session in [personal settings](https://fly.customer.io/settings/personal/).

## Find your workspace[](#find-your-workspace)

When you use Customer.io MCP, you’ll need to tell your AI tool which workspace to work in. You can select a workspace by name or by ID.

[![The workspace name in the upper-left and the ID in the URL](https://docs.customer.io/images/workspace-name-and-id.png)](#1d50ed57282137f499ab3fd99d679b8f-lightbox)

## Manage your MCP sessions[](#manage-your-mcp-sessions)

To see active sessions or revoke a connection, go to [**Settings > Personal Settings**](https://fly.customer.io/settings/personal/) and click **View sessions** under *Connected clients*. Revoking a session ends it immediately and forces the client to re-authenticate.

[![A cursor session shown in Customer.io](https://docs.customer.io/images/mcp-token-revoke.png)](#cee3c5829ae7b132b314e43f88c41989-lightbox)

## Install and troubleshoot SDKs[](#install-and-troubleshoot-sdks)

Customer.io MCP includes skills that can help you install and troubleshoot any of our SDK-based integrations, including [mobile SDKs](/integrations/sdk/) or any of our web-based integrations like our JavaScript client.

You can ask your AI tool questions like:

*   *Can you help me integrate with the Customer.io SDK for iOS?*
*   *My users aren’t receiving push notifications on Android. Can you help me troubleshoot?*

Your AI tool will help you update your code and return detailed steps to help you find and troubleshoot issues.

### 403 errors after a successful connection[](#403-errors-after-a-successful-connection)

If your MCP tool can connect and authenticate but every tool call fails with a `403`, your account admin probably turned off the **Customer.io MCP** toggle. Customer.io checks the toggle on every request, so a freshly authorized client still gets rejected if the toggle is off. Ask your admin to re-enable MCP in [Privacy, Data, & AI settings](https://fly.customer.io/settings/privacy/).

### Troubleshooting OAuth client not found error[](#troubleshooting-oauth-client-not-found-error)

If you see an “OAuth client not found” error, it means the connection between your MCP tool and Customer.io expired or was reset during the authorization process.

This typically happens when your AI tool (like Claude or Cursor) restarts, disconnects, or refreshes its connection while you’re completing the authorization flow. If you complete authorization in a browser tab from a previous connection attempt, Customer.io can’t find the original session and returns this error.

To fix the error, try the following things:

1.  Close any open “Customer.io authorization” browser tabs.
2.  Fully remove the Customer.io connection.
3.  Restart your AI tool.
4.  Re-add the Customer.io MCP connection from scratch.
5.  Complete the authorization flow only in the newly opened browser tab.