Skip to main content

Model Context Protocol Integration

EventPanel provides an MCP server that enables AI assistants like Cursor to automatically migrate events from your codebase and design documents into your EventPanel workspace, add new events as you develop, and update existing ones.

What is MCP?​

Model Context Protocol (MCP) is an open protocol that enables AI assistants to securely connect to external data sources and tools. The EventPanel MCP server empowers AI agents to:

  • Migrate events from code: Extract event definitions from your existing codebase (Swift, Kotlin, TypeScript, etc.) and import them into EventPanel
  • Migrate events from design docs: Parse product specifications, design documents, and requirements to create event definitions
  • Add new events: Let AI agents help you define and add new events to your workspace as you build features
  • Update existing events: Modify event names, descriptions, categories, properties, or sources on events already in your workspace
  • Archive events: Soft-delete events that are no longer needed, removing them from workspace queries

Setup​

Step 1: Generate API Token​

  1. Log in to your EventPanel workspace
  2. Navigate to Settings → API Tokens
  3. Click Create New Token
  4. Fill in:
    • Name: e.g., "Cursor MCP Integration"
    • Permissions: Select Read & Write permission
  5. Click Create and copy the token immediately

Step 2: Configure Cursor​

URLs (do not confuse these):

  • MCP endpoint (Cursor / SSE client): https://eventpanel.net/mcp — this is the protocol URL, not a page you open in a normal browser tab.
  • Human-readable guide (this page on production): https://eventpanel.net/docs/mcp — Traefik serves docs under /docs; the MCP server keeps /mcp for clients only.

  1. Open Cursor Settings (Cmd/Ctrl + ,) → Features → Model Context Protocol

  2. Add EventPanel MCP server configuration:

    {
      "mcpServers": {
        "eventpanel": {
          "url": "https://eventpanel.net/mcp",
          "headers": {
            "x-api-key": "YOUR_API_TOKEN_HERE"
          }
        }
      }
    }

  3. Replace YOUR_API_TOKEN_HERE with your token. Use the same header name in any other MCP-compatible client that supports remote servers over HTTP/SSE.

  4. Restart Cursor

Example Prompts​

Migrate Events from Code​

Analyze this codebase and find all analytics tracking calls. 
Extract event names, properties, and types, then migrate them to EventPanel.
Search for all analytics.track(), logEvent(), and similar calls in this project. 
Create events in EventPanel for each one with their properties.

Migrate Events from Design Docs​

Read this design document and extract all event tracking requirements. 
Create events in EventPanel with descriptions, categories, and properties based on the requirements.
Parse this PRD and identify all events that should be tracked. 
Add them to EventPanel with appropriate categories and property definitions.

Add New Events​

I'm building a checkout flow. What events should I track? 
Create them in EventPanel with appropriate properties like amount, currency, and productIds.
Based on this feature code, suggest and add tracking events to EventPanel. 
Include all relevant properties with correct types.
I need to track user onboarding steps. Create events for each step 
(signup_started, signup_completed, onboarding_completed) and add them to EventPanel.

Update Existing Events​

Rename the "user_signup" event to "user_registered" in EventPanel.
Add a "currency" STRING property and a "total_amount" FLOAT property 
to the checkout_completed event in EventPanel.
Update the description of the "page_viewed" event to clarify 
it fires on both web and mobile. Also add the "Mobile" source.

Archive Events​

Archive the "legacy_signup" event in EventPanel, it's been replaced by "user_registered".
Remove the deprecated checkout events from EventPanel.
Archive "checkout_v1_started" and "checkout_v1_completed".

Token usage and expiry​

Run get_token_context and tell me when my API token expires and how many times it has been used.
Before we add twenty events, call get_token_context so I can see current token usage.

How It Works​

The MCP server exposes seven tools that the AI assistant can invoke:

ToolDescription
add_eventCreate a single event in your workspace
get_eventGet a single event by its externalId
update_eventUpdate an existing event by its externalId
archive_eventSoft-delete an event by its externalId
get_eventsRetrieve events filtered by category names, sources, and/or labels (arrays; OR within each list, AND across lists)
get_contextWorkspace summary — id, name, counts, sample category/property names
get_token_contextToken health for the connected API key — usage count, last used, expiry, workspace id/name and timestamps

get_token_context — token usage and expiry​

Call this tool with no arguments ({}). It uses the same x-api-key you configured for MCP and returns read-only metadata about that token and its workspace.

Why it matters

  • Usage (tokenUsedCount) — how many times this token has been used (MCP and related API traffic). Helps you notice spikes after heavy agent sessions or scripts.
  • Last used (tokenLastUsedAt) — when the token was last used (ISO timestamp, or null if never).
  • Expiry (tokenExpiresAt) — when the token stops working unless renewed in Settings → API Tokens. Plan rotations before this date so assistants do not lose access mid-session.
  • Workspace — confirms which workspace the token is tied to (workspaceId, workspaceName), plus workspaceCreatedAt / workspaceUpdatedAt for context.

When to ask your assistant

  • “Run get_token_context and tell me if my MCP token is close to expiring.”
  • “Check token usage after that migration — did we burn a lot of calls?”
  • “Verify which workspace this Cursor MCP key is using.”

Self-hosted operators: the EventPanel MCP server must reach mcp-api (see your deployment’s MCP_API_BASE_URL). If get_context works but get_token_context fails, check routing from mcp-server to mcp-api.

Adding events​

The AI assistant uses add_event when you ask it to migrate or create events. Each call accepts a single event; to handle multiple events (e.g. from a codebase or design doc), the assistant calls add_event once per event.

Each event payload can include:

  • name (required): Event identifier
  • description: What the event tracks
  • categories: Grouping (e.g., "User", "E-COMMERCE")
  • properties: Event parameters with types (STRING, INTEGER, FLOAT, BOOLEAN, DATE, STRING_LIST, etc.) and required flags
  • sources: Platforms where used (iOS, Android, Web). Source names are matched case-insensitively (e.g. ios, iOS, and Ios all match a source named "iOS")

The assistant analyzes your code or docs, structures each event, and adds them to your workspace one at a time via repeated add_event invocations.

Updating events​

To modify an existing event, the assistant uses update_event with the event's externalId and one or more fields to change. At least one field must be provided.

Updatable fields:

  • name: Rename the event (must be unique within the workspace)
  • description: Change or set the event description
  • categories: Replace the event's categories
  • properties: Replace the event's properties (supports isRequired flag)
  • sources: Replace the event's sources (matched case-insensitively)

Relation arrays (categories, properties, sources) use replace semantics — the provided array fully replaces the existing relations. Send an empty array to clear all relations of that type. Omitted fields are left unchanged.

Archiving events​

To soft-delete an event, the assistant uses archive_event with the event's externalId. The event will no longer appear in workspace queries but remains in the database. Archiving bumps the event version. Note: events created via MCP with the same name as an archived event do not automatically restore the archived event; a new event is created instead.

Troubleshooting​

Connection issues: Verify your API token has Read & Write permissions and the client URL is https://eventpanel.net/mcp (not the /docs/... documentation path)

Authentication errors: Check that x-api-key header is set correctly in Cursor settings

Import errors: Ensure your token has Write permission and required fields are provided

Update errors: Check that the externalId matches an existing event and at least one update field is provided

Archive errors: Verify the externalId matches a non-archived event. Archiving an already-archived event returns a 404

Next Steps​