Outlit MCP Server

Query customer intelligence data through 6 MCP tools covering customer and user profiles, revenue metrics, activity timelines, and raw SQL analytics access.

Quick Start

| What you need | Tool | |---------------|------| | Browse/filter customers | outlit_list_customers | | Browse/filter users | outlit_list_users | | Single customer deep dive | outlit_get_customer | | Customer activity history | outlit_get_timeline | | Custom analytics / aggregations | outlit_query (SQL) | | Discover tables & columns | outlit_schema |

Before writing SQL: Always call outlit_schema first to discover available tables and columns.

Common Patterns

Find at-risk customers:

{
  "tool": "outlit_list_customers",
  "billingStatus": "PAYING",
  "noActivityInLast": "30d",
  "orderBy": "mrr_cents",
  "orderDirection": "desc"
}

Revenue breakdown (SQL):

{
  "tool": "outlit_query",
  "sql": "SELECT billing_status, count(*) as customers, sum(mrr_cents)/100 as mrr_dollars FROM customer_dimensions GROUP BY 1 ORDER BY 3 DESC"
}

MCP Setup

Get an API Key

Go to Settings > MCP Integration in the Outlit dashboard (app.outlit.ai).

Auto-Detection Setup

Detect the current environment and run the appropriate setup command:

Check for Claude Code — If running inside Claude Code (check if claude CLI is available), run:

claude mcp add outlit https://mcp.outlit.ai/mcp -- --header "Authorization: Bearer API_KEY"

Check for Cursor — If .cursor/mcp.json exists in the project or home directory, add to that file:

{
  "mcpServers": {
    "outlit": {
      "url": "https://mcp.outlit.ai/mcp",
      "headers": { "Authorization": "Bearer API_KEY" }
    }
  }
}

Check for Claude Desktop — If claude_desktop_config.json exists at ~/Library/Application Support/Claude/ (macOS) or %APPDATA%/Claude/ (Windows), add to that file:

{
  "mcpServers": {
    "outlit": {
      "url": "https://mcp.outlit.ai/mcp",
      "headers": { "Authorization": "Bearer API_KEY" }
    }
  }
}

Ask the user for their API key if not provided. Replace API_KEY with the actual key.

Verify Connection

Call outlit_schema to confirm the connection is working.

Tool Reference

outlit_list_customers

Filter and paginate customers.

| Key Params | Values | |------------|--------| | billingStatus | NONE, TRIALING, PAYING, CHURNED | | hasActivityInLast / noActivityInLast | 7d, 14d, 30d, 90d (mutually exclusive) | | mrrAbove / mrrBelow | cents (10000 = $100) | | search | name or domain | | orderBy | last_activity_at, first_seen_at, name, mrr_cents | | limit | 1-1000 (default: 20) | | cursor | pagination token |

outlit_list_users

Filter and paginate users.

| Key Params | Values | |------------|--------| | journeyStage | DISCOVERED, SIGNED_UP, ACTIVATED, ENGAGED, INACTIVE | | customerId | filter by customer | | hasActivityInLast / noActivityInLast | Nd, Nh, or Nm (e.g., 7d, 24h) — mutually exclusive | | search | email or name | | orderBy | last_activity_at, first_seen_at, email | | limit | 1-1000 (default: 20) | | cursor | pagination token |

outlit_get_customer

Single customer deep dive. Accepts customer ID, domain, or name.

| Key Params | Values | |------------|--------| | customer | customer ID, domain, or name (required) | | include | users, revenue, recentTimeline, behaviorMetrics | | timeframe | 7d, 14d, 30d, 90d (default: 30d) |

Only request the include sections you need — omitting unused ones is faster.

outlit_get_timeline

Activity timeline for a customer.

| Key Params | Values | |------------|--------| | customer | customer ID or domain (required) | | channels | SDK, EMAIL, SLACK, CALL, CRM, BILLING, SUPPORT, INTERNAL | | eventTypes | filter by specific event types | | timeframe | 7d, 14d, 30d, 90d, all (default: 30d) | | startDate / endDate | ISO 8601 (mutually exclusive with timeframe) | | limit | 1-1000 (default: 50) | | cursor | pagination token |

outlit_query

Raw SQL against ClickHouse analytics tables. SELECT only. See SQL Reference for ClickHouse syntax and security model.

| Key Params | Values | |------------|--------| | sql | SQL SELECT query (required) | | limit | 1-10000 (default: 1000) |

Available tables: events, customer_dimensions, user_dimensions, mrr_snapshots.

outlit_schema

Discover tables and columns. Call with no params for all tables, or table: "events" for a specific table. Always call this before writing SQL.

Data Model

Billing status: NONE → TRIALING → PAYING → CHURNED

Journey stages: DISCOVERED → SIGNED_UP → ACTIVATED → ENGAGED → INACTIVE

Data formats:

Monetary values in cents (divide by 100 for dollars)
Timestamps in ISO 8601
IDs with string prefixes (cust_, contact_, evt_)

Pagination: All list endpoints use cursor-based pagination. Check pagination.hasMore before requesting more pages. Pass pagination.nextCursor as cursor for the next page.

Best Practices

Call outlit_schema before writing SQL — discover columns, don't guess
Use customer tools for single lookups — don't use SQL for individual customer queries
Filter at the source — use tool params and WHERE clauses, not post-fetch filtering
Only request needed includes — omit unused include options for faster responses
Always add time filters to event SQL — WHERE occurred_at >= now() - INTERVAL N DAY
Convert cents to dollars — divide monetary values by 100 for display
Use LIMIT in SQL — cap result sets to avoid large data transfers

Known Limitations

SQL is read-only — no INSERT, UPDATE, DELETE
Organization isolation — cannot query other organizations' data
Timeline requires a customer — cannot query timeline across all customers
MRR filtering is post-fetch — may be slower on large datasets in list_customers
Event queries need time filters — queries without date ranges scan all data
ClickHouse syntax — uses different functions than MySQL/PostgreSQL (see SQL Reference)

Tool Gotchas

| Tool | Gotcha | |------|--------| | outlit_list_customers | hasActivityInLast and noActivityInLast are mutually exclusive | | outlit_list_customers | search checks name and domain only | | outlit_get_customer | behaviorMetrics depends on timeframe — extend it if empty | | outlit_get_timeline | timeframe and startDate/endDate are mutually exclusive | | outlit_query | Use ClickHouse date syntax: now() - INTERVAL 30 DAY, not DATE_SUB() | | outlit_query | properties column is JSON — use JSONExtractString(properties, 'key') |

References

| Reference | When to Read | |-----------|--------------| | SQL Reference | ClickHouse syntax, security model, query patterns | | Workflows | Multi-step analysis: churn risk, revenue dashboards, account health |