MCP Quickstart
Connect your AI agent to HeadlessAnalytics via Model Context Protocol in under 5 minutes.
1. Install the MCP Server
npm install -g @headlessanalytics/mcp
2. Configure Your Agent
Add the MCP server to your agent's configuration. The server connects via stdio transport.
{
"mcpServers": {
"headlessanalytics": {
"command": "ha-mcp",
"env": {
"HA_API_KEY": "ha_live_...",
"HA_API_URL": "https://api.headlessanalytics.com"
}
}
}
}3. Available Tools
Every tool returns a proof envelope with query metadata for auditability:
business_healthbusinessId?, limit?Operational health score with event counts, revenue, leads, orders, and actionable signals.
query_funnelsteps[], businessId?, from?, to?, limit?Step-by-step conversion rates, dropoffs, and flow-through metrics.
whats_changedcurrentFrom, currentTo, previousFrom, previousTo, businessId?, limit?Compare two time periods: event diffs, revenue changes, new/disappeared event types.
event_searchquery?, event?, actorType?, businessId?, from?, to?, limit?Free-text search across event names, properties, and actors with time range filtering.
4. Example: Agent Memory Loop
Your agent can use these tools to build persistent memory across sessions:
# 1. Check what changed since last session whats_changed( currentFrom: Date.now() - 86400000, currentTo: Date.now(), previousFrom: lastSessionTimestamp, previousTo: currentFrom ) # 2. Search for specific agent actions event_search( actorType: "agent", event: "agent.run_completed", from: lastSessionTimestamp ) # 3. Get health with proof for audit business_health(businessId: "default")
5. Proof Envelope
Every query returns data wrapped in a proof envelope for verification and audit trails:
{
"data": { ... },
"proof": {
"queryId": "q_1718456789_abc123",
"workspaceId": "w_...",
"businessId": "b_...",
"period": { "from": 1718370389, "to": 1718456789 },
"generatedAt": 1718456789000,
"schemaVersion": "1.0"
}
}Give Your Agent a Memory.
API keys in minutes. Proof envelopes on every query. Capture canonical events from apps, agents, and trackables — headless by default.
- 1Create a workspace
- 2Get API keys
- 3Send your first event