# Countly MCP

> Countly lets you monitor user behavior and app performance by connecting your analytics data directly to your AI agent. Track every user session, log custom actions, and run deep queries on behavioral metrics without leaving your chat window.

## Overview
- **Category:** data-analytics
- **Price:** Free
- **Tags:** product-analytics, user-tracking, event-logging, session-management, data-segmentation

## Description

Need to know *why* users are dropping off? This MCP connects your Countly instance, letting you query product behavior using simple conversation. Instead of digging through complex dashboards or exporting CSVs, you just ask your agent about user activity. You can track when a session starts and ends, log specific actions like button clicks or feature views, and even update user profiles on the fly. This ability to turn raw analytics data into conversational answers is huge. Through Vinkius, you get access to this tool alongside thousands of others, making it your central hub for all data sources. It’s about getting immediate insights—figuring out which features are used most often or finding exactly where users struggle.

## Tools

### begin_session
Starts tracking a new session for a specific user.

### end_session
Stops the current recorded user session.

### read_drill
Runs complex filtering and deep analysis on your data, typically for enterprise use cases.

### read_events
Pulls specific records related to custom user actions or events that occurred in the app.

### read_metrics
Retrieves general, high-level metrics like total sessions, unique users, or country counts.

### record_events
Logs specific actions that happen inside the application, including custom data keys and counts.

### update_session
Extends an existing session to keep the user active in the tracking system.

### update_user_details
Modifies stored information about a specific user, such as their name or email address.

## Prompt Examples

**Prompt:** 
```
Fetch the session metrics for my application.
```

**Response:** 
```
I've retrieved the session metrics. In the last period, there were 1,250 total sessions with an average duration of 4 minutes and 12 seconds per user.
```

**Prompt:** 
```
Record a 'purchase' event for device ID 'user_99' with a sum of 49.99.
```

**Response:** 
```
The 'purchase' event has been successfully recorded for device 'user_99' with the specified value. Countly has acknowledged the data point.
```

**Prompt:** 
```
Update user details for device 'dev_123' setting the email to 'test@example.com'.
```

**Response:** 
```
I have updated the profile for device 'dev_123'. The email address is now set to 'test@example.com' in your Countly user database.
```

## Capabilities

### Track user journeys
Start and stop tracking a user's activity to measure how long they stay engaged in the app.

### Log specific actions
Record custom events—like a purchase or clicking 'save'—with details about what happened and who did it.

### Get overall usage stats
Retrieve standard metrics, such as total sessions, number of unique users, or regional breakdowns.

### Deep-dive into segmented data
Run advanced filters to isolate specific user groups or complex behavioral patterns within your dataset.

### Update profile details
Modify core user information, like names or emails, directly in the analytics record.

## Use Cases

### Investigating sudden drop-off points
A PM notices usage dropped after the last release. They ask the agent: 'What were the recorded events immediately before users stopped logging in?' The agent uses `read_events` to pull a list of actions, helping them identify if a specific required step broke.

### Auditing onboarding completion
A Growth Marketer needs to know how many new users actually reached the final stage of signup. They ask the agent to check 'successful signups' metrics, triggering `read_metrics` for a clean count.

### Tracking complex user roles
A Data Analyst needs to filter all data only for users who are both in California and used the premium feature. They ask the agent to run an advanced query, using `read_drill` to get a precise segment count.

### Simulating user interaction flow
A tester wants to map out the full journey of a new user. They instruct their AI client to simulate a path: 'Begin session, record event for viewing dashboard, update user details with test email.' The agent runs `begin_session`, then `record_events`, and finally `update_user_details`.

## Benefits

- You get real-time session visibility. Use `begin_session` and `end_session` to track engagement duration instantly, so you never lose track of an active user flow.
- Pinpoint feature usage with custom logging. The `record_events` tool lets you log specific actions (like 'downloaded PDF' or 'used filter') for granular analysis.
- Bypass surface-level reports using `read_metrics`. You can ask the agent for aggregate data—total sessions by country, for example—without opening a single dashboard tab.
- Isolate niche user groups with precision. The `read_drill` tool lets you run complex filters to analyze deep segments that standard reporting tools miss.
- Maintain clean user records using `update_user_details`. You can keep your data accurate by letting the agent update names or emails when they change.
- Keep sessions running smoothly. If a user is active for a long time, use `update_session` to extend their tracked time without manually refreshing anything.

## How It Works

The bottom line is that your AI agent talks directly to your analytics backend, so you get answers without opening a separate dashboard.

1. First, subscribe to this MCP and provide your Countly Server URL along with the necessary API keys (App Key, App ID).
2. Next, you talk to your AI client using natural language. You ask questions like 'What were the total sessions last week?' or 'Record a purchase event for user X.'
3. The MCP runs those instructions against Countly and sends back structured, conversational data about what happened.

## Frequently Asked Questions

**How does Countly MCP help me track a session?**
You start tracking with `begin_session` when the app loads. You can keep it active using `update_session` and stop it with `end_session` once the user leaves.

**Can I use read_metrics for detailed event data?**
No, they do different things. Use `read_metrics` for broad numbers (like total users). If you need to know about a specific action, like 'purchase,' you must use `read_events`.

**What if I need to update user data mid-flow?**
You can modify records using the `update_user_details` tool. This allows you to change a user's name or email address directly from your chat conversation, keeping your dataset current.

**Is read_drill better than read_metrics?**
Yes, generally. `read_metrics` gives simple counts; `read_drill` lets you run much more advanced, complex filtering across multiple data dimensions for deeper analysis.

**When should I use `update_session` instead of letting time pass?**
You use `update_session` when you need to confirm user activity and extend the session duration actively. This is crucial for accurate tracking, especially if your app has periods of inactivity but the user remains engaged. It prevents premature session termination reported by the system.

**How do I properly use `record_events` when my action has multiple key-value pairs?**
You pass custom keys and corresponding values as structured data points within the `record_events` call. This allows you to track detailed context, like grouping an event by both a user ID and a specific feature version simultaneously. It makes your analytics much richer.

**If I run into issues using `read_metrics`, what should I check first?**
First, confirm the API Key and App ID you provided to this MCP are current and active in Countly. Most metric retrieval failures come down to expired or revoked credentials. Re-verify your connection details before assuming a data issue.

**Does using `read_drill` require special licensing or setup?**
Yes, accessing advanced filtering via the `read_drill` tool requires an Enterprise Edition license for Countly. If you get an error related to scope or permission, it means your account needs that specific upgrade to perform deep-dive analysis.

**How can I retrieve aggregated data like total sessions or user counts?**
You can use the `read_metrics` tool. Simply specify the method (e.g., 'sessions' or 'users') to get the aggregated analytics data from your Countly instance.

**Can I record custom user actions with metadata?**
Yes! Use the `record_events` tool. You can provide a device ID and an array of event objects containing keys, counts, and segmentation details to track specific interactions.

**Does this server support advanced filtering for Enterprise users?**
Yes, if you have the Enterprise Edition, you can use the `read_drill` tool to perform complex queries and segmentation using the Drill API.