Cairo Documentation

Cairo is a headless, MCP-first customer data platform. Agents are the primary user. This document describes how to connect, authenticate, and call every available tool.

Also: /llms.txt (agent-readable summary) · /.well-known/mcp.json (machine-readable discovery) · /mcp (MCP JSON-RPC endpoint) · /health (health)

Overview

Cairo exposes its capabilities as an MCP (Model Context Protocol) server over HTTP. Agents send JSON-RPC requests to POST /mcp and receive structured JSON responses. The same capabilities are also exposed as REST endpoints for backward compatibility with existing tools (Segment-compatible event ingestion, REST CRUD for destinations, etc.).

There is no UI. Everything is done through MCP or REST.

Authentication

All requests to /mcp require a write key. Pass it as one of:

X-Write-Key: your-key
Authorization: Bearer your-key

Any non-empty key is currently accepted. Fine-grained key validation (per-namespace scopes, rate limits) is on the roadmap.

MCP protocol

Cairo implements MCP protocol version 2024-11-05 over the Streamable HTTP transport. All requests are JSON-RPC 2.0.

initialize

Handshake. Returns protocol version, server info, and capabilities.

curl -X POST https://cairo.ani.computer/mcp \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
Response:
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "serverInfo": { "name": "cairo-cdp", "version": "2.0.0" },
    "capabilities": { "tools": {} }
  }
}

tools/list

Returns every available tool with its name, description, and input schema.

curl -X POST https://cairo.ani.computer/mcp \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

tools/call

Invoke a tool. The result is returned inside result.content as an array of MCP content blocks. Cairo always returns one text block containing the stringified JSON response.

curl -X POST https://cairo.ani.computer/mcp \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{
    "name":"track_event",
    "arguments":{"event":"signup","user_email":"jane@example.com"}
  }}'
Response:
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      { "type": "text", "text": "{\n  \"tracked\": true,\n  \"event\": \"signup\",\n  \"event_key\": \"mcp-signup-jane@example.com-1234567890\"\n}" }
    ]
  }
}

ping

Liveness check. Returns empty result.

curl -X POST https://cairo.ani.computer/mcp \
  -H "X-Write-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":99,"method":"ping"}'

Error codes

CodeMeaning
-32000Missing write key
-32600Invalid request (missing method)
-32601Method not found
-32603Internal error (uncaught exception)

Batch mode is supported: send a JSON array of JSON-RPC requests, receive an array of responses.

Tool reference (32)

Every capability Cairo offers is an MCP tool. Each section below lists arguments and a working curl example. Required arguments are marked; everything else is optional.

Events

track_event

Track a CDP event (page view, click, purchase, custom event).

ArgumentTypeDescription
event (required)stringEvent name
user_idstringUser ID
user_emailstringUser email
anonymous_idstringAnonymous ID
propertiesobjectEvent properties
namespacestringNamespace (default: "default")

Example:

curl -X POST https://cairo.ani.computer/mcp \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"track_event","arguments":{"event":"<event>"}}}'

batch_track

Track multiple events in a single call. Each item needs at least an event name.

ArgumentTypeDescription
events (required)arrayArray of event objects
namespacestringNamespace for all events

Example:

curl -X POST https://cairo.ani.computer/mcp \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"batch_track","arguments":{"events":[]}}}'

query_events

Query CDP events with filters. Returns recent events matching criteria.

ArgumentTypeDescription
event_typestringFilter by event type
user_emailstringFilter by user email
platformstringFilter by platform
limitnumberMax results (default 20)
sincestringISO timestamp: only events after this time

Example:

curl -X POST https://cairo.ani.computer/mcp \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"query_events","arguments":{}}}'

Users

identify_user

Identify a user with traits (email, name, plan, etc.).

ArgumentTypeDescription
user_id (required)stringUser ID
emailstringEmail address
traitsobjectUser traits
namespacestringNamespace

Example:

curl -X POST https://cairo.ani.computer/mcp \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"identify_user","arguments":{"user_id":"<user_id>"}}}'

lookup_user

Look up a user by email. Returns profile, traits, and recent activity.

ArgumentTypeDescription
email (required)stringUser email to look up

Example:

curl -X POST https://cairo.ani.computer/mcp \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"lookup_user","arguments":{"email":"<email>"}}}'

Identity

resolve_identity

Resolve the identity graph for a user across IDs, emails, and anonymous IDs.

ArgumentTypeDescription
user_idstringUser ID
emailstringEmail
anonymous_idstringAnonymous ID
namespacestringNamespace

Example:

curl -X POST https://cairo.ani.computer/mcp \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"resolve_identity","arguments":{}}}'

alias_identity

Link two user identities together (e.g., anonymous ID to known user).

ArgumentTypeDescription
previous_id (required)stringPrevious user ID or anonymous ID
user_id (required)stringNew canonical user ID
namespacestringNamespace

Example:

curl -X POST https://cairo.ani.computer/mcp \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"alias_identity","arguments":{"previous_id":"<previous_id>","user_id":"<user_id>"}}}'

Error tracking

capture_error

Capture an error event (like Sentry). Supports stack traces, context, and tagging.

ArgumentTypeDescription
message (required)stringError message
stack_tracestringStack trace
typestringError type (error, exception, rejection)
levelstringSeverity: fatal, error, warning, info
source_filestringSource file path
source_linenumberLine number
user_emailstringAffected user email
contextobjectAdditional context
tagsobjectTags for filtering
releasestringRelease/version
environmentstringEnvironment (production, staging)
namespacestringNamespace

Example:

curl -X POST https://cairo.ani.computer/mcp \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"capture_error","arguments":{"message":"<message>"}}}'

list_error_groups

List error groups (like Sentry issues). Filter by status.

ArgumentTypeDescription
statusstringFilter: open, resolved, ignored, regressed
namespacestringNamespace
limitnumberMax results (default 20)

Example:

curl -X POST https://cairo.ani.computer/mcp \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_error_groups","arguments":{}}}'

get_error_group

Get details of a specific error group by fingerprint.

ArgumentTypeDescription
fingerprint (required)stringError group fingerprint

Example:

curl -X POST https://cairo.ani.computer/mcp \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_error_group","arguments":{"fingerprint":"<fingerprint>"}}}'

resolve_error

Update an error group status to resolved, ignored, or reopen it.

ArgumentTypeDescription
fingerprint (required)stringError group fingerprint
status (required)stringNew status: open, resolved, ignored
assigned_tostringAssign to (email or name)

Example:

curl -X POST https://cairo.ani.computer/mcp \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"resolve_error","arguments":{"fingerprint":"<fingerprint>","status":"<status>"}}}'

Destinations

list_destinations

List configured event destinations and their status.

ArgumentTypeDescription
namespacestringNamespace (default: "default")

Example:

curl -X POST https://cairo.ani.computer/mcp \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_destinations","arguments":{}}}'

list_destination_types

List all available destination types (Mixpanel, Slack, BigQuery, etc.).

No arguments.

Example:

curl -X POST https://cairo.ani.computer/mcp \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_destination_types","arguments":{}}}'

create_destination

Create a new event destination configuration.

ArgumentTypeDescription
name (required)stringDestination name
type (required)stringDestination type (e.g., mixpanel, slack, bigquery)
namespacestringNamespace
configobjectDestination-specific config (API keys, URLs, etc.)
event_typesarrayEvent types to forward (default: all)

Example:

curl -X POST https://cairo.ani.computer/mcp \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"create_destination","arguments":{"name":"<name>","type":"<type>"}}}'

update_destination

Update an existing destination configuration.

ArgumentTypeDescription
id (required)stringDestination config ID
namestringNew name
configobjectUpdated config
enabledbooleanEnable or disable
event_typesarrayUpdated event types

Example:

curl -X POST https://cairo.ani.computer/mcp \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"update_destination","arguments":{"id":"<id>"}}}'

delete_destination

Delete a destination configuration.

ArgumentTypeDescription
id (required)stringDestination config ID

Example:

curl -X POST https://cairo.ani.computer/mcp \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"delete_destination","arguments":{"id":"<id>"}}}'

Transformations

list_transformations

List event transformation rules for a namespace.

ArgumentTypeDescription
namespacestringNamespace (default: "default")

Example:

curl -X POST https://cairo.ani.computer/mcp \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_transformations","arguments":{}}}'

create_transformation

Create a new event transformation rule (JavaScript function).

ArgumentTypeDescription
name (required)stringTransformation name
code (required)stringJavaScript transformation function body
namespacestringNamespace
destination_idstringApply only to this destination
execution_ordernumberOrder of execution (lower runs first)

Example:

curl -X POST https://cairo.ani.computer/mcp \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"create_transformation","arguments":{"name":"<name>","code":"<code>"}}}'

update_transformation

Update an existing transformation rule.

ArgumentTypeDescription
id (required)stringTransformation ID
namestring
codestring
enabledboolean

Example:

curl -X POST https://cairo.ani.computer/mcp \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"update_transformation","arguments":{"id":"<id>"}}}'

delete_transformation

Delete a transformation rule.

ArgumentTypeDescription
id (required)stringTransformation ID

Example:

curl -X POST https://cairo.ani.computer/mcp \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"delete_transformation","arguments":{"id":"<id>"}}}'

Tracking plans

list_tracking_plans

List tracking plans (event schemas and validation rules).

ArgumentTypeDescription
namespacestringNamespace (default: "default")

Example:

curl -X POST https://cairo.ani.computer/mcp \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_tracking_plans","arguments":{}}}'

create_tracking_plan

Create a new tracking plan with event schema validation.

ArgumentTypeDescription
name (required)stringPlan name
namespacestringNamespace
enforcement_modestringallow, warn, or drop
schemaobjectJSON Schema for event validation

Example:

curl -X POST https://cairo.ani.computer/mcp \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"create_tracking_plan","arguments":{"name":"<name>"}}}'

update_tracking_plan

Update an existing tracking plan.

ArgumentTypeDescription
id (required)stringPlan ID
namestring
enforcement_modestring
schemaobject

Example:

curl -X POST https://cairo.ani.computer/mcp \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"update_tracking_plan","arguments":{"id":"<id>"}}}'

delete_tracking_plan

Delete a tracking plan.

ArgumentTypeDescription
id (required)stringPlan ID

Example:

curl -X POST https://cairo.ani.computer/mcp \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"delete_tracking_plan","arguments":{"id":"<id>"}}}'

GDPR

gdpr_delete_user

Delete a user and all their data (GDPR right to erasure).

ArgumentTypeDescription
user_id (required)stringUser ID or email to delete
namespacestringNamespace

Example:

curl -X POST https://cairo.ani.computer/mcp \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"gdpr_delete_user","arguments":{"user_id":"<user_id>"}}}'

gdpr_suppress_user

Suppress a user so no new events are stored for them.

ArgumentTypeDescription
user_id (required)stringUser ID or email
reasonstringReason for suppression
namespacestringNamespace

Example:

curl -X POST https://cairo.ani.computer/mcp \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"gdpr_suppress_user","arguments":{"user_id":"<user_id>"}}}'

gdpr_unsuppress_user

Remove suppression for a user.

ArgumentTypeDescription
user_id (required)stringUser ID or email
namespacestringNamespace

Example:

curl -X POST https://cairo.ani.computer/mcp \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"gdpr_unsuppress_user","arguments":{"user_id":"<user_id>"}}}'

gdpr_check_suppression

Check if a user is currently suppressed.

ArgumentTypeDescription
user_id (required)stringUser ID or email
namespacestringNamespace

Example:

curl -X POST https://cairo.ani.computer/mcp \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"gdpr_check_suppression","arguments":{"user_id":"<user_id>"}}}'

Agent observability

query_agent_sessions

Query AI agent tracking sessions. See which agents ran, their costs, and outcomes.

ArgumentTypeDescription
agent_idstringFilter by agent ID
namespacestringNamespace
statusstringFilter: active, completed
limitnumberMax results (default 20)

Example:

curl -X POST https://cairo.ani.computer/mcp \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"query_agent_sessions","arguments":{}}}'

System

system_health

Get Cairo system health: database status, uptime, event counts, error counts.

No arguments.

Example:

curl -X POST https://cairo.ani.computer/mcp \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"system_health","arguments":{}}}'

describe_tool

Get detailed description, input schema, and usage example for any MCP tool.

ArgumentTypeDescription
tool_name (required)stringName of the tool to describe

Example:

curl -X POST https://cairo.ani.computer/mcp \
  -H "Content-Type: application/json" \
  -H "X-Write-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"describe_tool","arguments":{"tool_name":"<tool_name>"}}}'

REST compatibility

Cairo exposes Segment-compatible REST endpoints for existing client libraries. All also accept the X-Write-Key header.

EndpointMethodDescription
/api/v2/trackPOSTTrack a single event
/api/v2/batchPOSTTrack many events
/api/v2/identifyPOSTIdentify a user
/api/v2/pagePOSTPage view
/api/v2/screenPOSTScreen view (mobile)
/api/v2/groupPOSTAssociate user with group
/api/v2/aliasPOSTLink two identities
/api/v2/errors/capturePOSTCapture an error
/api/v2/identities/resolveGETResolve identity graph
/api/v2/destinationsGET/POSTDestination CRUD
/api/v2/transformationsGET/POSTTransformation CRUD
/api/v2/tracking-plansGET/POSTTracking plan CRUD
/api/v2/users/:userIdDELETEGDPR delete

SDKs

PackageUse for
@cairo/trackerUniversal event tracking from apps
@cairo/agent-trackerAI agent session tracking (generations, tool calls, costs)
@cairo/agent-mcpstdio MCP server for Claude Code, Cursor, and other agents
@cairo/node-sdkNode.js server-side SDK

stdio MCP for Claude Code / Cursor

{
  "mcpServers": {
    "cairo": {
      "command": "npx",
      "args": ["-y", "@cairo/agent-mcp"],
      "env": {
        "CAIRO_HOST": "https://cairo.ani.computer",
        "CAIRO_WRITE_KEY": "your-write-key",
        "CAIRO_AGENT_ID": "my-agent"
      }
    }
  }
}

Self-hosting

Cairo is Node.js + PostgreSQL. MIT licensed.

git clone https://github.com/outcome-driven-studio/cairo.git
cd cairo
npm install
cp .env.example .env
# Set POSTGRES_URL in .env
npm run migrate
npm start

Source: github.com/outcome-driven-studio/cairo