Model Context Protocol (MCP) Server

AI-powered integrations with Appizer data and functionality

The Model Context Protocol (MCP) is a standard that connects AI systems with Appizer's data and functionality. MCP allows external AI models to access your organization's data in a secure and controlled manner.

Overview

MCP provides a standardized way for AI systems to:

  • Access app data, events, and user information
  • Query audience segments
  • Retrieve analytics and insights
  • Perform operations based on contextual understanding

Base URL

text
https://api.appizer.com/mcp

Authentication

MCP uses a dedicated API key for authentication. This key is separate from your regular Appizer API keys and can be managed in your organization settings.

text
X-MCP-API-Key: YOUR_MCP_API_KEY

Alternatively, for clients that only accept a bare URL (no custom headers), append the key as a querystring parameter on the same endpoint:

text
https://app.appizer.com/mcp?api_key=YOUR_MCP_API_KEY

The header takes precedence if both are supplied. Note that the querystring form may be captured in server access logs, since it is part of the request URL.

Security Warning: MCP API keys have broad access to your organization's data. Keep them secure and rotate them regularly.

Session Handshake (Streamable HTTP)

MCP uses a session-based Streamable HTTP flow:

  1. Call initialize
  2. Read the returned transport.sessionId
  3. Send MCP-Session-Id (or X-MCP-Session-Id) on subsequent calls such as tools/list

Editor Config

Different MCP clients expect different config keys:

Windsurf

Windsurf expects serverUrl.

json
{
  "mcpServers": {
    "appizer": {
      "serverUrl": "https://app.appizer.com/mcp",
      "headers": { "X-MCP-API-Key": "YOUR_MCP_API_KEY" }
    }
  }
}

SSE-based editors

Some editors expect url instead of serverUrl:

json
{
  "mcpServers": {
    "appizer": {
      "url": "https://app.appizer.com/mcp",
      "headers": { "X-MCP-API-Key": "YOUR_MCP_API_KEY" }
    }
  }
}

Cursor IDE

Cursor uses url and stores config in ~/.cursor/mcp_config.json:

json
{
  "mcpServers": {
    "appizer": {
      "url": "https://app.appizer.com/mcp",
      "headers": { "X-MCP-API-Key": "YOUR_MCP_API_KEY" }
    }
  }
}

Setup:

  1. Open Cursor Settings (Cmd/Ctrl + ,)
  2. Search for "MCP" or navigate to Features → Model Context Protocol
  3. Click "Edit Config" to open the config file
  4. Add the Appizer configuration above
  5. Restart Cursor

Claude Desktop

Claude Desktop uses url and stores config in ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

json
{
  "mcpServers": {
    "appizer": {
      "url": "https://app.appizer.com/mcp",
      "headers": { "X-MCP-API-Key": "YOUR_MCP_API_KEY" }
    }
  }
}

Claude Code

Claude Code requires explicit transport specification for HTTP servers. You can configure it via CLI or JSON.

CLI Configuration (Recommended):

bash
claude mcp add --transport http appizer https://app.appizer.com/mcp \
  --header "X-MCP-API-Key: YOUR_MCP_API_KEY"

Important: The --transport http flag is required. Without it, Claude Code will not recognize the server correctly.

JSON Configuration:

Add to ~/.claude.json (user scope) or .mcp.json (project scope):

json
{
  "mcpServers": {
    "appizer": {
      "transport": "http",
      "url": "https://app.appizer.com/mcp",
      "headers": { "X-MCP-API-Key": "YOUR_MCP_API_KEY" }
    }
  }
}

Verify Connection:

bash
claude mcp list
claude mcp get appizer

Google Antigravity

Google Antigravity uses serverUrl and is configured via Extensions → Model Context Protocol:

json
{
  "mcpServers": {
    "appizer": {
      "serverUrl": "https://app.appizer.com/mcp",
      "headers": { "X-MCP-API-Key": "YOUR_MCP_API_KEY" }
    }
  }
}

Setup:

  1. Open Antigravity settings
  2. Navigate to Extensions → Model Context Protocol
  3. Add the Appizer configuration above
  4. Restart Antigravity

Available Endpoints

Server Information

text
GET /mcp

Returns information about the MCP server implementation.

Response:

json
{
  "name": "Appizer MCP Server",
  "version": "1.0",
  "status": "active",
  "timestamp": "2025-07-19T22:37:38-05:00"
}

Validate Authentication

text
GET /mcp/auth

Validates the MCP API key and returns organization information.

Response:

json
{
  "authenticated": true,
  "organization": {
    "id": "org_123",
    "name": "Acme Corp",
    "description": "Enterprise solutions",
    "timezone": "America/New_York"
  },
  "permissions": ["read", "write"],
  "protocol_version": "1.0"
}

List Available Resources

text
GET /mcp/resources

Returns a list of resources available through the MCP server.

Response:

json
{
  "resources": {
    "apps": [
      {
        "id": "app_123",
        "name": "Mobile App",
        "description": "iOS and Android app",
        "type": "app",
        "uri": "/mcp/resources/apps/app_123"
      }
    ],
    "audiences": [
      {
        "id": "aud_456",
        "name": "Active Users",
        "description": "Users active in the last 30 days",
        "type": "audience",
        "app_id": "app_123",
        "uri": "/mcp/resources/audiences/aud_456"
      }
    ]
  }
}

Get App Details

text
GET /mcp/resources/apps/:appId

Returns detailed information about a specific app.

Response:

json
{
  "id": "app_123",
  "name": "Mobile App",
  "description": "iOS and Android app",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-07-01T14:22:10Z",
  "stats": {
    "users": 15420,
    "events": 982345,
    "last_activity": "2025-07-19T21:15:33Z"
  },
  "top_events": [
    {
      "name": "app_open",
      "count": 45678
    },
    {
      "name": "purchase",
      "count": 2341
    }
  ]
}

Query Events

text
GET /mcp/events

Allows querying events with various filters.

Parameters:

  • app_id - Filter by app ID
  • event_name - Filter by event name
  • user_id - Filter by user ID
  • limit - Maximum number of results (default: 100, max: 1000)
  • offset - Pagination offset (default: 0)

Response:

json
{
  "events": [
    {
      "id": "evt_789",
      "app_id": "app_123",
      "user_id": "user_456",
      "event_name": "purchase",
      "properties": {
        "amount": 49.99,
        "item": "Premium Plan"
      },
      "created_at": "2025-07-19T20:15:33Z"
    }
  ],
  "pagination": {
    "total": 982345,
    "limit": 100,
    "offset": 0,
    "has_more": true
  }
}

Common Use Cases

Agentic Coding Assistant

Implement an AI coding assistant that can access your app's event data to suggest code improvements or debug issues.

Customer Support AI

Build a support chatbot that can access user data and event history to provide personalized assistance.

AI-Powered Analytics

Generate insights and visualizations from your app data using AI.

Security Best Practices

  • Rotate your MCP API keys regularly
  • Monitor MCP usage for unusual patterns
  • Limit MCP access to trusted AI systems
  • Review the data accessible through MCP
  • Disable MCP when not in use

Important: MCP provides AI systems with access to your organization's data. Always review what data is being shared and with which systems.

Next Steps

On this page