# Customers.ai MCP MCP

> Customers.ai lets you identify anonymous website visitors by name and turn them into actionable leads directly from your AI agent. You can search contact databases, add custom tags, update attributes, and send rich messages or SMS texts across multiple channels.

## Overview
- **Category:** productivity
- **Price:** Free
- **Tags:** customersai, identity-resolution, messaging-automation, lead-generation, x-ray-pixel, marketing-api, sms-automation, audience-segmentation, mcp

## Description

This MCP connects your automated messaging and B2B identity resolution to your natural language agent. When a prospect visits your site, you don't have to manually scrub through visitor logs; the AI does it for you. It identifies anonymous traffic, prioritizing high-intent leads so you know exactly who to talk to next. You can then use the agent to find contacts by email or phone number and update their records with specific details. Need to segment them? The agent handles that, allowing you to add tags and update custom attributes instantly. Finally, once a lead is qualified, your AI sends out targeted outreach via rich JSON messages or simple SMS texts, keeping your follow-up consistent across all channels. Because credentials pass through Vinkius's zero-trust proxy, your keys are used only in transit—they never sit on disk. This keeps your sensitive contact data secure while letting you run complex campaigns.

## Tools

### add_tag_to_contact
Applies a custom tag to an existing contact record.

### get_contact
Retrieves all profile details for a specified contact by ID or identifier.

### list_xray_leads
Provides a list of website visitors who have been identified via X-Ray Pixel tracking.

### remove_tag_from_contact
Deletes one or more tags from a contact record.

### search_contacts
Searches the entire database of contacts using specific criteria like email or name.

### send_rich_message
Sends a highly structured, formatted message containing buttons and galleries across chat channels.

### send_text_message
Sends simple, plain text messages via SMS to a contact's phone number.

### update_contact_attributes
Changes specific pieces of information or custom data points on a contact profile.

## Prompt Examples

**Prompt:** 
```
List the last 5 leads identified via X-Ray Pixel.
```

**Response:** 
```
I've retrieved your recent X-Ray leads. I found 5 identified visitors, including profiles for managers at 'Acme Corp' and 'Global Tech'. Would you like the detailed attributes for any of them?
```

**Prompt:** 
```
Find the contact with email 'jane.doe@example.com'.
```

**Response:** 
```
I've located Jane Doe's profile (ID: 1024). She has 15 custom attributes and is currently tagged as 'Hot Lead'. Shall I send her a follow-up text message?
```

**Prompt:** 
```
Add the 'Q2 Campaign' tag to contact ID '1024'.
```

**Response:** 
```
Action complete! Contact 1024 has been successfully tagged with 'Q2 Campaign'. This update can now trigger your automated nurturing sequences. Need help with other tags?
```

## Capabilities

### Find identified prospects
Retrieve detailed metadata and lists of website visitors captured by X-Ray Pixel.

### Search your entire contact base
Locate any existing contact profile using criteria like email or phone number.

### Send structured messages
Dispatch complex, formatted messages that include buttons and galleries across chat channels.

### Send standard SMS alerts
Transmit simple, plain text messages to a specific contact's phone number.

### Update lead records
Programmatically modify custom attributes and audience tags on any contact profile.

## Use Cases

### A site visitor leaves without converting.
The problem is that a high-value prospect visits your pricing page but vanishes. You ask your agent to run `list_xray_leads` to identify them, find their full profile using `search_contacts`, and then send an immediate follow-up text message via `send_text_message` reminding them of the next steps.

### A campaign requires complex follow-up.
You need to qualify a list of leads. You ask your agent to use `get_contact` on several IDs, then apply a 'Hot Lead' tag using `add_tag_to_contact`, and finally send them a rich JSON message detailing the next steps.

### A lead record is missing key details.
An old contact profile needs current information. Your agent runs `update_contact_attributes` to add new department data, then uses `remove_tag_from_contact` to clean up outdated tags before a fresh outreach.

### Coordinating multi-touchpoint sales efforts.
A sale involves multiple teams. Your agent first finds the contact via email using `search_contacts`, then sends an introductory text message, and finally updates their status to 'Sales Qualified' using `update_contact_attributes`.

## Benefits

- Quickly find new opportunities: Use the `list_xray_leads` function to pull fresh data on anonymous website visitors without manual dashboard scrubbing.
- Maintain clean records: The agent lets you run `add_tag_to_contact` or `remove_tag_from_contact` instantly, keeping your audience segmentation accurate for campaigns.
- Multi-channel consistency: Whether it's a simple text alert via `send_text_message` or a detailed JSON message using `send_rich_message`, the outreach feels unified.
- Deep data access: You can use `get_contact` and then modify records with `update_contact_attributes` to build out a full prospect profile in one go.
- Focused searching: Use `search_contacts` when you need to find someone by email or phone, bypassing the need for multiple search tabs.

## How It Works

The bottom line is you get a single point of access to manage lead data—from discovery to initial outreach—without leaving your AI agent's chat window.

1. First, connect your API key to the MCP and establish context for a target lead (e.g., by asking your agent to find the name or email of an interested visitor).
2. Next, tell the agent what needs doing—maybe it needs to add a 'High Intent' tag or send a follow-up text message.
3. The platform executes the required actions, returning confirmation that the contact record was updated and/or the message was successfully sent.

## Frequently Asked Questions

**How do I list identified website visitors using the list_xray_leads tool?**
You prompt your agent to run `list_xray_leads`. The AI will retrieve a current list of all visitors identified by X-Ray Pixel, giving you metadata on who visited and when.

**Can I update contact attributes using the update_contact_attributes tool?**
Yes. You ask your agent to run `update_contact_attributes` and specify exactly what data needs changing (like a department or title) for a given contact ID.

**What's the difference between send_text_message and send_rich_message?**
Use `send_text_message` only when you need to send plain text, like a quick SMS reminder. Use `send_rich_message` for anything more complex that needs buttons or image galleries.

**How do I find an existing lead by phone number? (search_contacts)**
You instruct your agent to use the `search_contacts` tool, providing the contact's phone number as a parameter. The AI returns all matching profile data.

**What is the best way to manage audience segmentation using both `add_tag_to_contact` and `remove_tag_from_contact`?**
You control segments by directly manipulating tags. Use `add_tag_to_contact` when a lead meets criteria, like making a purchase. Always follow up with `remove_tag_from_contact` if that status changes or expires.

**If I use the `get_contact` tool, what specific metadata fields can my agent retrieve about a user's profile?**
The tool retrieves comprehensive contact details beyond just names and emails. You get access to custom attributes, historical tags, and detailed identity resolution pipeline data for full context.

**What happens if I run too many searches using the `search_contacts` tool in a short time?**
The system implements rate limiting to keep things stable. If you hit the limit, your agent will receive an explicit error code telling you how long to wait before trying again.

**How does my AI client handle failures when sending messages using `send_text_message`?**
The tool call returns a detailed status log. If the send fails, the log specifies the reason—like invalid phone number or carrier rejection—so you know exactly why it failed.