Segment Automation

1---
2name: segment-automation
3description: "Automate Segment tasks via Rube MCP (Composio): track events, identify users, manage groups, page views, aliases, batch operations. Always search tools first for current schemas."
4requires:
5  mcp: [rube]
6---
7 
8# Segment Automation via Rube MCP
9 
10Automate Segment customer data platform operations through Composio's Segment toolkit via Rube MCP.
11 
12## Prerequisites
13 
14- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
15- Active Segment connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `segment`
16- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
17 
18## Setup
19 
20**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
21 
22 
231. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
242. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `segment`
253. If connection is not ACTIVE, follow the returned auth link to complete Segment authentication
264. Confirm connection status shows ACTIVE before running any workflows
27 
28## Core Workflows
29 
30### 1. Track Events
31 
32**When to use**: User wants to send event data to Segment for downstream destinations
33 
34**Tool sequence**:
351. `SEGMENT_TRACK` - Send a single track event [Required]
36 
37**Key parameters**:
38- `userId`: User identifier (required if no `anonymousId`)
39- `anonymousId`: Anonymous identifier (required if no `userId`)
40- `event`: Event name (e.g., 'Order Completed', 'Button Clicked')
41- `properties`: Object with event-specific properties
42- `timestamp`: ISO 8601 timestamp (optional; defaults to server time)
43- `context`: Object with contextual metadata (IP, user agent, etc.)
44 
45**Pitfalls**:
46- At least one of `userId` or `anonymousId` is required
47- `event` name is required and should follow consistent naming conventions
48- Properties are freeform objects; ensure consistent schema across events
49- Timestamp must be ISO 8601 format (e.g., '2024-01-15T10:30:00Z')
50- Events are processed asynchronously; successful API response means accepted, not delivered
51 
52### 2. Identify Users
53 
54**When to use**: User wants to associate traits with a user profile in Segment
55 
56**Tool sequence**:
571. `SEGMENT_IDENTIFY` - Set user traits and identity [Required]
58 
59**Key parameters**:
60- `userId`: User identifier (required if no `anonymousId`)
61- `anonymousId`: Anonymous identifier
62- `traits`: Object with user properties (email, name, plan, etc.)
63- `timestamp`: ISO 8601 timestamp
64- `context`: Contextual metadata
65 
66**Pitfalls**:
67- At least one of `userId` or `anonymousId` is required
68- Traits are merged with existing traits, not replaced
69- To remove a trait, set it to `null`
70- Identify calls should be made before track calls for new users
71- Avoid sending PII in traits unless destinations are configured for it
72 
73### 3. Batch Operations
74 
75**When to use**: User wants to send multiple events, identifies, or other calls in a single request
76 
77**Tool sequence**:
781. `SEGMENT_BATCH` - Send multiple Segment calls in one request [Required]
79 
80**Key parameters**:
81- `batch`: Array of message objects, each with:
82  - `type`: Message type ('track', 'identify', 'group', 'page', 'alias')
83  - `userId` / `anonymousId`: User identifier
84  - Additional fields based on type (event, properties, traits, etc.)
85 
86**Pitfalls**:
87- Each message in the batch must have a valid `type` field
88- Maximum batch size limit applies; check schema for current limit
89- All messages in a batch are processed independently; one failure does not affect others
90- Each message must independently satisfy its type's requirements (e.g., track needs event name)
91- Batch is the most efficient way to send multiple calls; prefer over individual calls
92 
93### 4. Group Users
94 
95**When to use**: User wants to associate a user with a company, team, or organization
96 
97**Tool sequence**:
981. `SEGMENT_GROUP` - Associate user with a group [Required]
99 
100**Key parameters**:
101- `userId`: User identifier (required if no `anonymousId`)
102- `anonymousId`: Anonymous identifier
103- `groupId`: Group/organization identifier (required)
104- `traits`: Object with group properties (name, industry, size, plan)
105- `timestamp`: ISO 8601 timestamp
106 
107**Pitfalls**:
108- `groupId` is required; it identifies the company or organization
109- Group traits are merged with existing traits for that group
110- A user can belong to multiple groups
111- Group traits update the group profile, not the user profile
112 
113### 5. Track Page Views
114 
115**When to use**: User wants to record page view events in Segment
116 
117**Tool sequence**:
1181. `SEGMENT_PAGE` - Send a page view event [Required]
119 
120**Key parameters**:
121- `userId`: User identifier (required if no `anonymousId`)
122- `anonymousId`: Anonymous identifier
123- `name`: Page name (e.g., 'Home', 'Pricing', 'Dashboard')
124- `category`: Page category (e.g., 'Docs', 'Marketing')
125- `properties`: Object with page-specific properties (url, title, referrer)
126 
127**Pitfalls**:
128- At least one of `userId` or `anonymousId` is required
129- `name` and `category` are optional but recommended for proper analytics
130- Standard properties include `url`, `title`, `referrer`, `path`, `search`
131- Page calls are often automated; manual use is for server-side page tracking
132 
133### 6. Alias Users and Manage Sources
134 
135**When to use**: User wants to merge anonymous and identified users, or manage source configuration
136 
137**Tool sequence**:
1381. `SEGMENT_ALIAS` - Link two user identities together [Optional]
1392. `SEGMENT_LIST_SCHEMA_SETTINGS_IN_SOURCE` - View source schema settings [Optional]
1403. `SEGMENT_UPDATE_SOURCE` - Update source configuration [Optional]
141 
142**Key parameters**:
143- For ALIAS:
144  - `userId`: New user identifier (the identified ID)
145  - `previousId`: Old user identifier (the anonymous ID)
146- For source operations:
147  - `sourceId`: Source identifier
148 
149**Pitfalls**:
150- ALIAS is a one-way operation; cannot be undone
151- `previousId` is the anonymous/old ID, `userId` is the new/identified ID
152- Not all destinations support alias calls; check destination documentation
153- ALIAS should be called once when a user first identifies (e.g., signs up)
154- Source updates may affect data collection; review changes carefully
155 
156## Common Patterns
157 
158### User Lifecycle
159 
160Standard Segment user lifecycle:
161```
1621. Anonymous user visits -> PAGE call with anonymousId
1632. User interacts -> TRACK call with anonymousId
1643. User signs up -> ALIAS (anonymousId -> userId), then IDENTIFY with traits
1654. User takes action -> TRACK call with userId
1665. User joins org -> GROUP call linking userId to groupId
167```
168 
169### Batch Optimization
170 
171For bulk data ingestion:
172```
1731. Collect events in memory (array of message objects)
1742. Each message includes type, userId/anonymousId, and type-specific fields
1753. Call SEGMENT_BATCH with the collected messages
1764. Check response for any individual message errors
177```
178 
179### Naming Conventions
180 
181Segment recommends consistent event naming:
182- **Events**: Use "Object Action" format (e.g., 'Order Completed', 'Article Viewed')
183- **Properties**: Use snake_case (e.g., 'order_total', 'product_name')
184- **Traits**: Use snake_case (e.g., 'first_name', 'plan_type')
185 
186## Known Pitfalls
187 
188**Identity Resolution**:
189- Always include `userId` or `anonymousId` on every call
190- Use ALIAS only once per user identity merge
191- Identify before tracking to ensure proper user association
192 
193**Data Quality**:
194- Event names should be consistent across all sources
195- Properties should follow a defined schema for downstream compatibility
196- Avoid sending sensitive PII unless destinations are configured for it
197 
198**Rate Limits**:
199- Use BATCH for bulk operations to stay within rate limits
200- Individual calls are rate-limited per source
201- Batch calls are more efficient and less likely to be throttled
202 
203**Response Parsing**:
204- Successful responses indicate acceptance, not delivery to destinations
205- Response data may be nested under `data` key
206- Check for error fields in batch responses for individual message failures
207 
208**Timestamps**:
209- Must be ISO 8601 format with timezone (e.g., '2024-01-15T10:30:00Z')
210- Omitting timestamp uses server receive time
211- Historical data imports should include explicit timestamps
212 
213## Quick Reference
214 
215| Task | Tool Slug | Key Params |
216|------|-----------|------------|
217| Track event | SEGMENT_TRACK | userId, event, properties |
218| Identify user | SEGMENT_IDENTIFY | userId, traits |
219| Batch calls | SEGMENT_BATCH | batch (array of messages) |
220| Group user | SEGMENT_GROUP | userId, groupId, traits |
221| Page view | SEGMENT_PAGE | userId, name, properties |
222| Alias identity | SEGMENT_ALIAS | userId, previousId |
223| Source schema | SEGMENT_LIST_SCHEMA_SETTINGS_IN_SOURCE | sourceId |
224| Update source | SEGMENT_UPDATE_SOURCE | sourceId |
225| Warehouses | SEGMENT_LIST_CONNECTED_WAREHOUSES_FROM_SOURCE | sourceId |
226