docs: MoEngage MCP segmentation tool belt (14 tools)

[claude]

Requested by Tanmay Kasliwal · Slack thread

Before

The segmentation MCP tool belt shipped to production on 2026-07-22 with no customer-facing documentation — the MCP page's Segments table listed only the original 5 tools, with no parameters, examples, or caveats anywhere.

After

The full 14-tool segmentation belt is documented in the MCP section: a new detailed page (per-tool purpose, parameters, examples, caveats, recommended workflow) plus an updated tool table on the main MCP page linking to it.

How

• New page user-guide/ai-and-intelligence/merlin-ai/moengage-mcp-segmentation-tools.mdx, registered in docs.json as a sibling of moengage-mcp-server.
• Extended the Segments table in moengage-mcp-server.mdx with the 6 new tools.
• Source of truth: tool definitions in external-moengage-mcp-server agentcore/tools/{custom_segments_v5,recent_query_v5,discovery}.py (docstrings + client-side validation), cross-checked against agentcore/CLAUDE.md tool tables.
• Screenshots intentionally omitted — TODO markers left for the tech-writer pass (Shubhra Pati).

Open questions for technical review

1. Recent-query prod scope: announcement listed create_recent_query + get_recent_query_filters; the page also documents get_recent_query (needed to poll results) — confirm it's live, and whether list_recent_queries, get_recent_query_users, rerun_recent_query, update_recent_query_mail should be documented too.
2. describe_segment_filters prod routing: agentcore notes flag it as the first /v2 path needing gateway route/gatekeeper onboarding — confirm routing is complete.
3. find_event_attributes: in code and required for event-property filters but absent from the announcement's discovery list — confirm it's in the prod set.
4. DC availability: confirm the segmentation belt is live on all four DCs the connector page claims.
5. Role/permission mapping: exact permission required for segment/query write tools (page uses generic "create/manage permission" language).
6. get_recent_query status vocabulary (success vs finished) and failure_reason field name — taken from docstrings, not a live spec.

---

Generated by Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
moengage	🟢 Ready	View Preview	Jul 24, 2026, 12:59 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[claude]

Engineering review pass on the four open items (2026-07-27). Findings below with code evidence; page updated in 0355af20 on this branch.

1. Reachability parameter shape (create_recent_query)

The per-channel empty objects are the minimal valid form, not the only form — but the parameter is currently overridden server-side anyway.

• The authoritative spec (moengage/dashboard-segmentation → api-specs/recent-query/v5_api_spec.yaml) defines ReachabilityChannelRequest with all-nullable fields: platforms ("Needed for push reachability only, e.g. [ANDROID, iOS]"), aggregated_count_required (bool), and reachability_column ("Needed for email/sms/whatsapp reachability"). So {"push": {}, "email": {}} is just "these channels, defaults for everything"; channel keys can hold config.
• However, the MCP-facing v5 resource (recent-query-server/.../public_resources/recent_queries_resource.py, RecentQueriesResourceV5.on_post) unconditionally replaces the client-sent value: body.reachability = self._get_default_reachability() → push {platforms: [ANDROID, iOS, web], aggregated_count_required: true}, email/sms/whatsapp {aggregated_count_required: true}. Whatever the tool forwards (it forwards the dict verbatim, agentcore/tools/recent_query_v5.py:199-200), you get all four channels with a push platform split.
• Same code path also forces body.channel_source = 'MCP' (CommonConstants.MCP_CHANNEL_SOURCE), so the tool's channel_source parameter ("default all" per its docstring) is also inert on this endpoint. The tool docstrings in external-moengage-mcp-server should be updated to match (follow-up for the MCP repo, not this docs PR).

Page change: the reachability row now documents the per-channel object shape, and a note states that reachability is currently computed with the fixed server-side configuration (all four channels, push split by platform). The channel_source row now says the server sets it to MCP.

2. Rate limits / quotas

Nothing is enforced at the tool layer. external-moengage-mcp-server has no client-side rate limiting, retry throttling, or quota logic (checked agentcore/clients/_base.py, all segmentation tools; the only client-side numeric guards are max 10 segment_ids, page_size 1–100). internal-docs/tools-roadmap.md (branch docs/internal-context-scaffold) has no limits either. What does exist:

• Segment count cache, 15 min — server-side, start_segment_count docstring (served_from_cache).
• Recent-query create dedup, 15 min default — RecentQueriesResourceV5.on_post hashes the request body into a Redis key (recent_query_{db_name}_{hash}) and returns the cached rq_id on a hit; TTL is recent_query.server.create_dedup_ttl_seconds, default 900 s (recent-query-server/.../config/provider.py). Identical create within 15 min = same rq_id, no new job.
• 429s exist in the upstream contract: the custom-segments v5 spec (moengage/custom-segments → api-specs/custom-segments/v5_api_spec.yaml) defines a RateLimited response (RATE_LIMIT_EXCEEDED, "Too many requests. Please retry after 60 seconds.") on at least the membership endpoint; is_user_in_segment's docstring documents 429. No numeric quota is published anywhere I can see.
• 413 on oversized/deep filter payloads (create segment + create recent query).
• Poll frequency and concurrent job counts: no enforced limits found; the 3–5 s / <30 s guidance in the docstrings is advisory only.

Unverified: gateway-level (SGK/APISIX) quotas. The gatekeeper/route configs live in InternalWorks repos I can't read from here; if per-route rate policies exist there, they're invisible to this review. Flagging plainly rather than guessing.

Page change: new "Limits" section (table of the verified numbers + a note that 429s can occur with ~60 s retry guidance and that the gateway can apply its own traffic controls, no published quota).

3. Canonical filter JSON shapes

Authoritative sources: agentcore/schemas/component/segment_filters.json (the discover_schema stub, ActionFilter path live-verified 2026-07-13), models/custom_segments_v5.py / models/recent_query_v5.py (informational FilterGroup), and the create_custom_segment docstring. Canonical shapes, now on the page:

• FilterGroup: {"filter_operator": "and"|"or", "filters": [...]} (non-empty).
• user_attributes: flat — filter_type, name, data_type, operator, value at top level (+ optional value1, value_type, negate, case_sensitive, array_filter_type).
• actions: nested — action_name, required attributes FilterGroup (empty no-op {"filter_operator":"and","filters":[]} when unused), execution {type: atleast|exactly|atmost, count}, primary_time_range {type, value, value1?, value_type, period_unit} (operator key is type, not operator_type).
• custom_segments: {"filter_type":"custom_segments","id":"<segment_id>","name":"<segment_name>"} — field is id, not segment_id.
• nested_filters: {"filter_type":"nested_filters","filter_operator":...,"filters":[...]} — one level only.

Known stub bugs (AILABS-122, filed 2026-07-23, still Backlog) — both confirmed and reflected on the page:

• The stub's operator matrix says string equals; the live API 400s on equals and accepts is (DC3 live proof: segment 6a6191b046e2c5b5ad388809, "moe_ip_city is Chennai", 201). Only string equality is live-verified; the rest of the stub's operator vocabulary comes from the v5 spec and was never verified end-to-end, which is why the page recommends deep_validate_segment_filters for operator compatibility rather than printing a full matrix.
• executed: false is a silent no-op (not an error, not a negation). The working negation is execution: {"type":"atmost","count":0} (DC3 live proof: segment 6a611a5fc1e7d4aac3fa4895, 201) — which the stub actively forbids via count.minimum: 1. The stub and the create_custom_segment/segmentation.json docstrings still need the AILABS-122 fixes in the MCP repo.

deep_validate_segment_filters is kept on the page as the recommended pre-create check, but no longer as the only source of truth for shapes.

4. Example verification on the page

• Mumbai walkthrough: "operator": "equals" was wrong (would 400 live) — fixed to "is". Everything else in that JSON checks out against the live-verified ActionFilter shape (required empty attributes, execution.atleast, primary_time_range keys).
• excluded_filters JSON (refund exclusion): correct as written — and notably it's the right negation pattern (positive filter in excluded_filters), unaffected by the executed:false bug. Added a warning nearby so nobody "simplifies" it into executed:false.
• node_attribute_name/cart_items example: verified against get_value_suggestions (custom_segments_v5.py:609-617; maps to body.node.{attribute_name,data_type}) — correct as written.
• get_recent_query polling text: verified and strengthened (see below).

Impact on the six original open questions

• Q6 (status vocabulary / failure_reason) — settled. The recent-query v5 spec defines RecentQueryStatus: [received, running, success, failure, retry_wait] and failure_reason as a real field. The page's success/failure language is correct (and now also lists the in-progress states). Segment count jobs separately use finished/failure — the page's split vocabulary is right, not a contradiction.
• Q1 (recent-query prod scope) — partial. All seven endpoints (list/create/get/filters/users/rerun/mail) are implemented and routed in the service's MCP-facing v5 app (recent-query-server/.../public_app_v5.py registers all six route names). Whether the gateway exposes all of them on every DC still needs InternalWorks confirmation.
• Q2 (describe routing), Q3 (find_event_attributes prod set), Q4 (DC availability), Q5 (permissions) — not resolvable from the repos available to this session. On Q5, the only concrete artifact found is the X-MOE-Scopes example in agentcore/CLAUDE.md showing a segments:view;create_manage resource entry, which supports the page's generic "create/manage permission" wording but doesn't confirm the exact mapping.

Unresolved / follow-ups (outside this PR)

• Gateway-level quotas: unknown, needs InternalWorks/SGK/APISIX review.
• AILABS-122 fixes to segment_filters.json, segmentation.json, and the create_custom_segment docstring in external-moengage-mcp-server (this PR only fixes the customer-facing page).
• Tool docstring corrections in the MCP repo for the server-overridden reachability and channel_source parameters on create_recent_query.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NScTkaj9Rhf2agPRBQvrWZ