MCP Tools | Appizer API Documentation

Complete reference for all tools available through the Appizer MCP server.

Available Tools

The Appizer MCP server provides the following tools for querying and managing your application data:

Data Query Tools

query_events - Query events with filters
query_users - Query user data
get_app_details - Get app statistics and metadata
get_audience_details - Get audience information
list_apps - List all apps in your organization
list_audiences - List audiences for an app

Campaign Management Tools

create_audience - Create audiences from natural language descriptions
create_push_campaign - Create push notification campaigns
list_push_campaigns - List push campaigns with filters

Event Dictionary Tools

list_event_dictionary - List event dictionary entries
update_event_definition - Update event definitions
auto_define_events - AI-powered batch event definition generation

query_events

Query events from Appizer with optional filters for app, event name, user, and pagination.

Parameters:

Parameter	Type	Required	Description
`app_id`	string	No	Filter events by app ID
`event_name`	string	No	Filter events by event name
`user_id`	string	No	Filter events by user ID
`start_date`	string	No	Start date (ISO 8601)
`end_date`	string	No	End date (ISO 8601)
`limit`	integer	No	Max results (default: 100, max: 1000)
`offset`	integer	No	Pagination offset (default: 0)

Example:

{
  "name": "query_events",
  "arguments": {
    "app_id": "123e4567-e89b-12d3-a456-426614174000",
    "event_name": "purchase_completed",
    "limit": 50
  }
}

Response:

{
  "events": [
    {
      "id": "evt_789",
      "app_id": "app_123",
      "user_id": "user_456",
      "event_name": "purchase_completed",
      "properties": {
        "amount": 49.99,
        "currency": "USD"
      },
      "created_at": "2025-07-19T20:15:33Z"
    }
  ],
  "pagination": {
    "total": 1234,
    "limit": 50,
    "offset": 0,
    "has_more": true
  }
}

query_users

Query app users with optional filters for user ID, email, and pagination.

Parameters:

Parameter	Type	Required	Description
`app_id`	string	Yes	App ID to query users from
`user_id`	string	No	Filter by specific user ID
`email`	string	No	Filter by email (partial match)
`limit`	integer	No	Max results (default: 100, max: 1000)
`offset`	integer	No	Pagination offset (default: 0)

Example:

{
  "name": "query_users",
  "arguments": {
    "app_id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "john",
    "limit": 20
  }
}

Response:

{
  "users": [
    {
      "user_id": "user-123",
      "properties": {
        "email": "john@example.com",
        "name": "John Doe"
      },
      "last_seen": "2026-01-22T15:30:00.000Z",
      "created_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 45,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}

get_app_details

Get detailed information about a specific app including statistics and top events.

Parameters:

Parameter	Type	Required	Description
`app_id`	string	Yes	App ID to retrieve details for

Example:

{
  "name": "get_app_details",
  "arguments": {
    "app_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Response:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "My App",
  "description": "Mobile app for iOS and Android",
  "created_at": "2025-01-01T00:00:00.000Z",
  "stats": {
    "users": 15234,
    "events": 456789,
    "last_activity": "2026-01-22T15:30:00.000Z"
  },
  "top_events": [
    {"name": "app_opened", "count": 123456},
    {"name": "purchase_completed", "count": 45678}
  ]
}

get_audience_details

Get detailed information about a specific audience including user count and criteria.

Parameters:

Parameter	Type	Required	Description
`audience_id`	string	Yes	Audience ID to retrieve details for

Example:

{
  "name": "get_audience_details",
  "arguments": {
    "audience_id": "789e4567-e89b-12d3-a456-426614174000"
  }
}

Response:

{
  "id": "789e4567-e89b-12d3-a456-426614174000",
  "name": "Active Users",
  "description": "Users who opened the app in the last 7 days",
  "app_id": "123e4567-e89b-12d3-a456-426614174000",
  "app_name": "My App",
  "created_at": "2025-06-01T00:00:00.000Z",
  "updated_at": "2026-01-22T15:30:00.000Z",
  "user_count": 5432,
  "criteria": {
    "event": "app_opened",
    "timeframe": "7d"
  }
}

list_apps

List all apps for the authenticated organization.

Parameters:

This tool takes no parameters.

Example:

{
  "name": "list_apps",
  "arguments": {}
}

Response:

{
  "apps": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "My App",
      "description": "Mobile app for iOS and Android",
      "created_at": "2025-01-01T00:00:00.000Z",
      "updated_at": "2026-01-22T15:30:00.000Z"
    }
  ],
  "total": 1
}

list_audiences

List all audiences for a specific app.

Parameters:

Parameter	Type	Required	Description
`app_id`	string	Yes	App ID to list audiences for

Example:

{
  "name": "list_audiences",
  "arguments": {
    "app_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Response:

{
  "app_id": "123e4567-e89b-12d3-a456-426614174000",
  "app_name": "My App",
  "audiences": [
    {
      "id": "789e4567-e89b-12d3-a456-426614174000",
      "name": "Active Users",
      "description": "Users who opened the app in the last 7 days",
      "created_at": "2025-06-01T00:00:00.000Z",
      "updated_at": "2026-01-22T15:30:00.000Z",
      "user_count": 5432
    }
  ],
  "total": 1
}

list_event_dictionary

List event dictionary entries for an app with optional filtering by archived status, undefined events, or search terms.

Parameters:

Parameter	Type	Required	Description
`app_id`	string	Yes	App ID to list events for
`archived`	boolean	No	Filter by archived status
`undefined_only`	boolean	No	Show only events without definitions (default: false)
`search`	string	No	Search event names (case-insensitive partial match)
`limit`	integer	No	Max results (default: 100, max: 1000)

Example:

{
  "name": "list_event_dictionary",
  "arguments": {
    "app_id": "123e4567-e89b-12d3-a456-426614174000",
    "undefined_only": true,
    "limit": 50
  }
}

Response:

{
  "app_id": "123e4567-e89b-12d3-a456-426614174000",
  "events": [
    {
      "id": "event-dict-uuid",
      "event_name": "purchase_completed",
      "user_definition": null,
      "event_count": 1234,
      "first_recorded_at": "2025-01-01T00:00:00.000Z",
      "last_recorded_at": "2026-01-22T15:30:00.000Z",
      "archived": false,
      "tracking_enabled": true
    }
  ],
  "total": 15,
  "undefined_count": 15
}

Use Cases:

Find all events that need definitions
Search for specific event patterns
Review archived events
Audit event tracking status

update_event_definition

Update the definition for a single event by ID or name. Can also be used to clear definitions or archive events.

Parameters:

Parameter	Type	Required	Description
`app_id`	string	Yes	App ID
`event_id`	string	No*	Event dictionary ID (use this OR event_name)
`event_name`	string	No*	Event name to update (use this OR event_id)
`definition`	string	No	New definition text (empty string to clear)
`archived`	boolean	No	Archive status

*At least one of event_id or event_name is required.

Security Note: Clearing all definitions (empty definition + no event_id/event_name) is only allowed from the dashboard, not via MCP.

Example:

{
  "name": "update_event_definition",
  "arguments": {
    "app_id": "123e4567-e89b-12d3-a456-426614174000",
    "event_name": "purchase_completed",
    "definition": "User successfully completed a purchase transaction"
  }
}

Response:

{
  "success": true,
  "event": {
    "id": "event-dict-uuid",
    "event_name": "purchase_completed",
    "user_definition": "User successfully completed a purchase transaction",
    "updated_at": "2026-01-22T15:30:00.000Z"
  }
}

auto_define_events

AI-powered batch definition generation for events. Analyzes event names, usage patterns, and sample data to generate meaningful definitions.

Parameters:

Parameter	Type	Required	Description
`app_id`	string	Yes	App ID
`mode`	string	No	"empty_only" (default) or "overwrite_all"
`dry_run`	boolean	No	Preview changes without saving (default: false)
`event_names`	array	No	Specific event names to process

Security Note: The "overwrite_all" mode is only allowed from the dashboard to prevent accidental overwrites via MCP.

Example:

{
  "name": "auto_define_events",
  "arguments": {
    "app_id": "123e4567-e89b-12d3-a456-426614174000",
    "mode": "empty_only",
    "dry_run": false
  }
}

Response:

{
  "processed": 15,
  "updated": 12,
  "skipped": 3,
  "dry_run": false,
  "events": [
    {
      "event_name": "purchase_completed",
      "definition": "User successfully completed a purchase transaction",
      "updated": true,
      "event_count": 1234,
      "context_used": {
        "sample_properties": ["amount", "currency", "product_id"],
        "related_events": ["purchase_started", "payment_processed"]
      }
    },
    {
      "event_name": "app_opened",
      "definition": "User launched the application",
      "updated": true,
      "event_count": 45678,
      "context_used": {
        "sample_properties": ["platform", "version"],
        "related_events": ["app_backgrounded", "app_closed"]
      }
    }
  ]
}

How It Works:

The AI analyzes multiple data points to generate accurate definitions:

Event Name Patterns - Analyzes naming conventions and structure
Usage Frequency - Considers how often the event occurs
Sample Properties - Reviews event property names and values
Related Events - Identifies commonly co-occurring events
Temporal Patterns - Examines when events typically occur

Use Cases:

Bulk-define events for new apps
Generate definitions for imported events
Preview AI-generated definitions before applying
Define specific events by name

create_audience

Create audiences from natural language descriptions using AI-powered SQL generation.

Parameters:

Parameter	Type	Required	Description
`app_id`	string	No	App ID (auto-selected if org has 1 app)
`name`	string	Yes	Audience name
`description`	string	Yes	Natural language description used as AI prompt

Example:

{
  "name": "create_audience",
  "arguments": {
    "name": "Inactive Users",
    "description": "users who haven't been active in 7 days"
  }
}

Security: Generated SQL is validated against a blocklist (no DROP/DELETE/UPDATE) and executed in read-only transactions with 30-second timeouts.

Response:

{
  "audience_id": "789e4567-e89b-12d3-a456-426614174000",
  "name": "Inactive Users",
  "description": "users who haven't been active in 7 days",
  "user_count": 1245,
  "sql_generated": true,
  "created_at": "2026-02-04T14:40:00Z"
}

create_push_campaign

Create push notification campaigns with optional AI-generated messages, audiences, and trigger event detection.

Parameters:

Parameter	Type	Required	Description
`app_id`	string	No	Target app (auto-selected if org has 1 app)
`name`	string	Yes	Campaign identifier
`title`	string	Yes	Push notification title
`message`	string	No*	Static message (if no prompt)
`prompt`	string	No*	AI prompt for message generation
`audience_id`	string	No	Existing audience to target
`audience_prompt`	string	No	Create audience from this prompt
`schedule_type`	string	Yes	scheduled, recurring, slipping_away, or trigger
`scheduled_at`	string	No	ISO 8601 datetime for scheduled
`trigger_event_name`	string	No	Exact event name for trigger campaigns
`trigger_event_prompt`	string	No	Natural language - AI matches to tracked events
`action_url`	string	No	URL to open on tap

*Either message or prompt is required.

Security Note: schedule_type: "now" is not supported via MCP to prevent accidental mass sends. Use the dashboard for immediate campaigns.

Example:

{
  "name": "create_push_campaign",
  "arguments": {
    "name": "Level Complete Celebration",
    "title": "Congratulations!",
    "prompt": "Send a congratulations message when user completes a level",
    "schedule_type": "trigger",
    "trigger_event_prompt": "when user finishes a level"
  }
}

Response:

{
  "campaign_id": "campaign-uuid",
  "name": "Level Complete Celebration",
  "status": "live",
  "schedule_type": "trigger",
  "trigger": {
    "event_name": "level_complete",
    "match_method": "llm_semantic",
    "available_events_count": 47
  },
  "message": {
    "title": "Congratulations!",
    "body": "Amazing work! You've completed another level. Keep up the great progress!",
    "generated": true
  },
  "created_at": "2026-02-04T14:39:00Z"
}

list_push_campaigns

List push notification campaigns for an app with optional status filtering and delivery stats.

Parameters:

Parameter	Type	Required	Description
`app_id`	string	No	Target app (auto-selected if org has 1 app)
`status`	string	No	Filter by: scheduled, live, paused, sent
`limit`	integer	No	Max results (default: 50)

Example:

{
  "name": "list_push_campaigns",
  "arguments": {
    "status": "live",
    "limit": 10
  }
}

Response:

{
  "campaigns": [
    {
      "id": "campaign-uuid",
      "name": "Re-engagement Campaign",
      "title": "We miss you!",
      "message": "Come back and check out our new features",
      "status": "live",
      "schedule_type": "trigger",
      "trigger_event": "app_opened",
      "audience_id": "audience-uuid",
      "audience_name": "Inactive Users",
      "created_at": "2026-01-15T10:00:00.000Z",
      "stats": {
        "sent": 1245,
        "delivered": 1180,
        "clicked": 89
      }
    }
  ],
  "total": 1
}

Common Patterns

Agentic Coding Environment

When using MCP tools in an agentic coding environment like Windsurf or Claude Code:

Event Discovery:

"List all events that don't have definitions yet"
"Show me the most frequently used events"
"Find events related to purchases"

Event Documentation:

"Auto-generate definitions for all undefined events"
"Update the definition for 'purchase_completed'"
"Preview AI-generated definitions without saving"

Campaign Creation:

"Create a re-engagement campaign for inactive users"
"Send a congratulations message when users complete a level"
"List all my active push campaigns"

Best Practices

Use dry_run first - Preview AI-generated changes before applying
Filter effectively - Use undefined_only to focus on events needing definitions
Batch operations - Use auto_define_events for multiple events at once
Security awareness - Understand MCP restrictions vs dashboard capabilities
Context matters - Provide clear descriptions for AI-powered tools

Error Handling

All tools return errors in a consistent format:

{
  "error": true,
  "message": "App not found or access denied",
  "tool": "list_event_dictionary"
}

Common error scenarios:

Invalid app_id - App doesn't exist or you don't have access
Missing parameters - Required parameters not provided
Permission denied - Operation restricted to dashboard only
Rate limit exceeded - Too many requests in a short time

Next Steps

MCP Authentication - Set up API keys
MCP Resources - Explore data resources
MCP Overview - Learn about MCP basics