# StatHat MCP

> StatHat lets your AI agent post custom metrics and statistics directly to your observability stack. Use StatHat's tools to increment counters, record specific values (like latency), or batch-update multiple stats without leaving your chat client. It’s built for developers who need real-time performance data logged instantly.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Tags:** metrics, statistics, tracking, monitoring, analytics

## Description

Forget writing boilerplate SDK code or manually updating dashboards just to log a metric. When you connect your AI client to **StatHat**, you're giving your agent an instant pipeline for performance data. It’s built for developers who need real-time tracking—you don't want to leave the chat window every time something happens, so StatHat lets your agent post custom metrics and stats directly to your observability stack using four specific tools.

When you use this server, your AI client acts as the bridge. Instead of telling your agent what to *do* with code, you just tell it what happened; then, the right tool handles sending that data instantly. You'll find the functionality covers everything from logging a single event count to dumping massive sets of diverse metrics all at once.

**Increment Event Counters:** You can use `post_classic_counter` when you need to track simple, discrete events. If something happens—say, a user clicks a specific button or an API call succeeds—you instruct your agent to run this tool, and it increases the count for that specific event key by exactly one. This is how you measure total occurrences of any defined action.

**Record Specific Numerical Values:** For continuous numbers, you'll use `post_classic_value`. Think latency measurements in milliseconds, CPU usage percentages, or resource availability; these are all values. When you call this tool, your agent sends a precise number to a dedicated stat key, allowing you to track rates and magnitudes over time.

**Create Metrics on the Fly:** Sometimes you don't know if a metric key exists yet—you just need to log it immediately. That’s where `post_ez_stat` comes in handy. You give this tool a descriptive name, and StatHat automatically handles creating the metric for you, logging that new stat without any setup required on your end.

**Batch Log Multiple Statistics:** When you're dealing with large amounts of data—maybe counts *and* values from several different sources at once—you don't want to make multiple API calls. You use `post_json_stats`. This tool accepts structured JSON data, letting you send diverse metrics (counts, specific numerical values, and timestamps) in a single, efficient call. It’s how you keep your logging fast when you're tracking everything.

If you need to track the number of times a user hit 'submit,' you invoke `post_classic_counter`. If you're measuring the average time it took for a database query to run, you use `post_classic_value` with that continuous time. Need to log a new metric called 'Payment Gateway Failures'? Use `post_ez_stat` just by giving it the name. And when your application generates dozens of data points—like counts from three different endpoints and values for two different service latencies—you bundle all that crap into one JSON payload using `post_json_stats`. This server gives you granular, immediate control over metrics logging without forcing you to write a single line of extra code.

## Tools

### post_classic_counter
Increments a specific metric counter, useful for tracking discrete event occurrences.

### post_classic_value
Sets or updates a stat with a continuous numerical value, like response time in milliseconds.

### post_ez_stat
Creates and posts a statistic using an easy name. It handles creating the metric automatically if it doesn't exist.

### post_json_stats
Accepts structured JSON data to post multiple different statistics (counts and values) in a single, efficient call.

## Prompt Examples

**Prompt:** 
```
Increment the 'Messages Processed' stat by 1 using StatHat EZ.
```

**Response:** 
```
I've successfully incremented the 'Messages Processed' counter. StatHat confirmed the update was received.
```

**Prompt:** 
```
Post a value of 45.5 to the stat key 'th789abc' using the classic API.
```

**Response:** 
```
The value 45.5 has been posted to stat key 'th789abc'. Your dashboard should reflect this update immediately.
```

**Prompt:** 
```
Batch update these stats: 'errors' count 5 and 'latency' value 120.
```

**Response:** 
```
I've sent the batch update for 'errors' and 'latency' via the JSON API. Both metrics have been updated.
```

## Capabilities

### Increment Event Counters
Use `post_classic_counter` to increase the count for any specific event key by exactly one.

### Record Specific Numerical Values
Send precise, continuous numbers—like latency or resource usage—to a dedicated stat key using `post_classic_value`.

### Create Metrics on the Fly
Invoke `post_ez_stat` to create and log an entirely new metric simply by providing a descriptive name, no setup required.

### Batch Log Multiple Statistics
Send large sets of diverse metrics (counts, values, timestamps) in one request using `post_json_stats` for efficiency.

## Use Cases

### Debugging Latency Spikes
A developer notices high latency during a specific API call. Instead of leaving the IDE to open monitoring tools, they prompt their agent: 'Log the current latency as 450ms for the 'checkout' stat key.' The agent runs `post_classic_value`, logging the exact metric without context switching.

### Tracking User Flow Funnel
A data analyst needs to know how many users hit the pricing page today. They prompt: 'Increment the counter for 'Pricing Page Views' by 1.' The agent uses `post_classic_counter` and immediately updates the core metric, helping track conversion rates in real-time.

### Post-Deployment Health Check
A DevOps engineer runs a batch test after deployment. They tell their agent: 'Report errors at 2 count, latency at 150ms value, and success status.' The agent executes `post_json_stats`, logging the full health snapshot with one command.

### A/B Testing Results
An analyst runs a test comparing two features. Instead of maintaining separate spreadsheets, they prompt: 'Log the conversion rate for Group A as 0.12 and Group B as 0.15.' The agent uses `post_classic_value` to record both metrics simultaneously.

## Benefits

- Directly log data from your chat client. You skip the steps of copy-pasting metrics into a separate dashboard or manually calling an SDK endpoint.
- Use `post_ez_stat` for quick wins. Need to track 'User Signups'? Just name it, and StatHat handles creating the metric key automatically.
- Process high volumes fast with `post_json_stats`. Instead of sending four separate messages for errors, latency, count, and status, you send them all in one JSON payload.
- Track continuous performance data. Use `post_classic_value` to record things like average response time or system temperature, giving you true observability numbers.
- Keep your workflow contained. Whether you're debugging from Cursor or running tasks from the terminal, all logging stays within the agent chat interface.

## How It Works

The bottom line is: you use your AI agent to talk to StatHat, and StatHat handles the data logging details for you.

1. Subscribe to the StatHat server and provide your EZ or User Key.
2. Tell your AI agent what metrics need logging (e.g., 'Increment user signups by 1').
3. The agent calls the appropriate tool (`post_classic_counter`, `post_ez_stat`, etc.), and StatHat confirms the metric update.

## Frequently Asked Questions

**How do I log a simple event count with post_classic_counter?**
Use `post_classic_counter` when you just need to increment an integer, like counting successful logins. You provide the key and the change amount; it's perfect for discrete events.

**What if I have several metrics (count, value, error) in one go? Which tool should I use?**
Use `post_json_stats`. This tool accepts a JSON array. It’s designed to handle multiple, different types of stats—counts and values—in a single request, keeping your logging clean.

**Is post_ez_stat better than post_classic_counter?**
They serve different purposes. Use `post_ez_stat` when you need to log an entirely new metric without knowing if the key exists first. Use `post_classic_counter` when you know the stat already exists and just needs a simple increment.

**Can I use post_classic_value for tracking user count?**
While technically possible, it's better practice to use `post_classic_counter`. Values are best for continuous data (like 45.5ms). Counters are meant specifically for whole, discrete event counts.

**How do I log a batch of metrics using post_json_stats?**
You send a JSON payload containing multiple key/value pairs. For example: `[{'key': 'errors', 'count': 5}, {'key': 'latency', 'value': 120}]`. This is the most efficient way to log.

**What keys do I need to authenticate when using post_ez_stat?**
You need your StatHat EZ Key or User Key. This key authenticates your AI agent and grants it access to the metrics endpoints, letting it log data without needing manual setup.

**How do I manually control the timestamp when calling post_json_stats?**
You can include an optional 't' field within the JSON object. This allows you to specify a precise timestamp for that particular metric entry, overriding the system's default logging time.

**What happens if I use post_classic_value with a stat key that doesn't exist?**
The API will return an error indicating an invalid or non-existent Stat Key. You must verify the spelling and format of your metric name before retrying the call.

**What is the difference between the EZ API and the Classic API?**
The EZ API (`post_ez_stat`) allows you to post stats using a simple human-readable name and your EZ Key. The Classic API (`post_classic_counter`, `post_classic_value`) requires a unique Stat Key for each specific metric, providing more granular control.

**Do I need to create a stat on the website before posting to it?**
No! When using the `post_ez_stat` tool, StatHat will automatically create the statistic for you if it doesn't already exist in your account.

**Can I send multiple metrics at once to save time?**
Yes, you can use the `post_json_stats` tool to send an array of multiple stat updates in a single network request.