> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcp-use.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Telemetry

> Understanding MCP-use's telemetry system

## Overview

MCP-use includes an **opt-out telemetry system** that helps us understand how the library is being used in practice. This data enables us to:

* **Prioritize development** based on real usage patterns
* **Optimize performance** for common workflows
* **Improve compatibility** with popular model providers
* **Focus on the most valuable features**

<Warning>
  **Privacy First**: All telemetry is **anonymized** and can be **completely disabled** with a single environment variable.
</Warning>

## What We Collect

### Agent Execution Data

When you use `MCPAgent.run()` or `MCPAgent.stream()`, we collect:

* **Query and response content** (to understand use cases)
* **Model provider and name** (e.g., "openai", "gpt-4")
* **MCP servers connected** (types and count, not specific URLs/paths)
* **Tools used** (which MCP tools are popular)
* **Performance metrics** (execution time, steps taken)
* **Configuration settings** (memory enabled, max steps, etc.)

### System Information

* **Package version** (for version adoption tracking)
* **Error types** (for debugging and improvement)
* **Package download analytics** (via Scarf for distribution insights)

### What We DON'T Collect

* **Personal information** (no names, emails, or identifiers)
* **Server URLs or file paths** (only connection types)
* **API keys or credentials** (never transmitted)
* **IP addresses** (PostHog configured with `disable_geoip=False`)

## How to Disable Telemetry

### Environment Variable (Recommended)

```bash theme={null}
export MCP_USE_ANONYMIZED_TELEMETRY=false
```

### In Your Code

```python theme={null}
import os
os.environ["MCP_USE_ANONYMIZED_TELEMETRY"] = "false"

# Now use MCP-use normally - no telemetry will be collected
from mcp_use import MCPAgent
```

### Verification

When telemetry is disabled, you'll see this debug message:

```
DEBUG: Telemetry disabled
```

When enabled, you'll see:

```
INFO: Anonymized telemetry enabled. Set MCP_USE_ANONYMIZED_TELEMETRY=false to disable.
```

## Data Storage and Privacy

### Anonymous User IDs

* A random UUID is generated and stored locally in your cache directory
* **Linux/Unix**: `~/.cache/mcp_use/telemetry_user_id`
* **macOS**: `~/Library/Caches/mcp_use/telemetry_user_id`
* **Windows**: `%LOCALAPPDATA%\mcp_use\telemetry_user_id`

### Data Transmission

* Data is sent to both **PostHog** (EU servers: `https://eu.i.posthog.com`) and **Scarf** (`https://mcpuse.gateway.scarf.sh/simple/`)
* **No personal information** is ever transmitted
* Data is used only for **aggregate analysis** and **package usage analytics**

## Example Telemetry Event

Here's what a typical telemetry event looks like:

```json theme={null}
{
  "event": "mcp_agent_execution",
  "distinct_id": "550e8400-e29b-41d4-a716-446655440000",
  "properties": {
    "mcp_use_version": "1.3.0",
    "execution_method": "run",
    "query": "Help me analyze sales data from the CSV file",
    "response": "I'll help you analyze the sales data...",
    "model_provider": "openai",
    "model_name": "gpt-4",
    "server_count": 2,
    "server_identifiers": [
      {"type": "stdio", "command": "python -m server"},
      {"type": "http", "base_url": "localhost:8080"}
    ],
    "tools_used_names": ["read_file", "analyze_data"],
    "execution_time_ms": 2500,
    "success": true
  }
}
```

## Benefits to the Community

### For Users

* **Better library** through data-driven improvements
* **Faster issue resolution** via error pattern detection
* **Feature prioritization** based on actual usage

### For Developers

* **Compatibility insights** for new model providers
* **Performance optimization** targets
* **Usage pattern understanding** for better APIs

## Technical Implementation

### Clean Architecture

The telemetry system uses a **decorator pattern** that ensures:

* **Zero overhead** when disabled
* **No exceptions** if PostHog or Scarf services are unavailable
* **Graceful degradation** in all failure scenarios
* **Dual telemetry** to both PostHog and Scarf for comprehensive analytics

### Code Example

```python theme={null}
# This is how telemetry works internally:
@requires_telemetry
def track_agent_execution(self, ...):
    # This method only executes if telemetry is enabled
    # If disabled, it returns None immediately
    pass
```

## Frequently Asked Questions

### Can I see what data is being sent?

Yes! Set your logging level to DEBUG to see telemetry events:

```python theme={null}
import logging
logging.basicConfig(level=logging.DEBUG)
```

### Does telemetry affect performance?

* **When disabled**: Zero performance impact
* **When enabled**: Minimal impact (async data transmission)

### Can I opt out after using the library?

Yes! Set the environment variable and restart your application. You can also delete the user ID file to reset your anonymous identifier.

### Is this GDPR compliant?

Yes. The telemetry system:

* Collects no personal data
* Uses anonymous identifiers
* Provides easy opt-out
* Processes data for legitimate business interests (software improvement)

## Support

If you have questions about telemetry:

* **Disable it**: Use `MCP_USE_ANONYMIZED_TELEMETRY=false`
* **Report issues**: [GitHub Issues](https://github.com/mcp-use/mcp-use/issues)
* **Check logs**: Enable DEBUG logging to see telemetry activity

<Note>
  Remember: Telemetry helps us build a better library for everyone, but **your privacy comes first**. We've designed the system to be transparent, minimal, and easily disabled.
</Note>