Get started with the Customer.io MCP server
UpdatedRecently updated
How it works
Customer.io MCP connects your Customer.io account to AI tools that support the Model Context Protocol. 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, Claude, and Cursor 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?
What can Customer.io 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
422error 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
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, Claude, or Cursor and other IDEs.
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.
Now you’re ready to set up your MCP client—see ChatGPT, Claude, or Cursor and other IDEs for help.
Enabling Customer.io AI also enables a set of AI features in your account across all team members
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
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.
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.
Manage your MCP sessions
To see active sessions or revoke a connection, go to Settings > Personal Settings and click View sessions under Connected clients. Revoking a session ends it immediately and forces the client to re-authenticate.
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 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
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.
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:
- Close any open “Customer.io authorization” browser tabs.
- Fully remove the Customer.io connection.
- Restart your AI tool.
- Re-add the Customer.io MCP connection from scratch.
- Complete the authorization flow only in the newly opened browser tab.
