Outlit MCP Server

Query customer intelligence data through 8 MCP tools covering customer profiles, user activity, facts, semantic search, revenue metrics, and raw SQL analytics.

Quick Start — Which Tool to Use

Facts vs Search vs Timeline — When to Use Each

These three tools all surface customer context but serve different purposes:

Rule of thumb: Use get_facts to browse, search_customer_context to answer questions, get_timeline to see chronology.

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"
}

Find context about a topic across all customers:

{
  "tool": "outlit_search_customer_context",
  "query": "data retention compliance concerns"
}

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:

1. 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"
   

2. 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" }
       }
     }
   }
   

3. 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

Browse and filter customers. Returns paginated list with summary info.

outlit_list_users

Browse and filter users. Returns paginated list with activity info.

outlit_get_customer

Full details for a single customer. Accepts customer ID, domain, or name.

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

outlit_get_timeline

Chronological activity timeline for a customer.

outlit_get_facts

List all structured facts known about a customer. Use outlit_search_customer_context instead if you have a specific question.

outlit_search_customer_context

Semantic + full-text search over customer context (facts and emails). Use this to answer specific questions. Omit customer to search across all customers.

outlit_query

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

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

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

Known Limitations

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

Tool Gotchas

References