MCPToolsCDP tools
Search Customers
Search your CDP customer profiles by email, phone, name, or id
cdp_search_customers
Searches your brand's CDP customer profiles by a substring over email, phone, name, or profile id. Results are partitioned into two buckets: customers (deterministically-resolved identities — real customers) and anonymous (pixel-only, cookie/UUID profiles with no resolved identity). Each returned row carries a per-row provenance label (server, pixel, or merged) so a merged master is never mistaken for one confirmed person.
Read-only and scoped to your brand. Use a returned profile itemId with cdp_customer_events and cdp_customer_sessions.
Parameters
| Name | Type | Required | Description | Default |
|---|---|---|---|---|
query | string | No | Substring matched (case-insensitive) over email / phone / name / profile id. | — |
bucket | string | No | customers (deterministic identities) or anonymous (pixel-only profiles). | customers |
provenance | string | No | Explicit provenance filter — pixel, server, merged, or all. Overrides the bucket mapping when set. | — |
limit | number | No | Page size (1–100). | 25 |
offset | number | No | Offset for offset-based paging. | 0 |
cursor | string | No | Opaque nextCursor from a previous page, to continue enumerating past the offset window. | — |
Returns
list— the matched profiles, each with its provenance label.identities— a map of profileitemId→ derived identity (email / phone / name).totalSize,offset,pageSize— paging metadata.scope— your brand's shop domain (every row is bound to it).nextCursor— pass back ascursorto walk the next page, ornullwhen the walk is exhausted.
Example prompts
Find customers whose email contains "gmail"Search my anonymous profiles for the phone number ending 0123Notes
- Every search is bound to your brand's scope server-side, so another brand's profiles can never appear.
- For large result sets, follow
nextCursorrather than deep offsets. - The
identitiesmap lets you turn a matched profile into a readable customer without a second lookup.