# Use AI Observability over PostHog MCP - Docs

The [PostHog MCP server](/docs/model-context-protocol.md) lets your AI coding agent query [LLM traces](/docs/ai-observability.md) directly from your code editor. Check costs, monitor errors, and analyze model performance – without switching to the PostHog app.

This works in any MCP client – Cursor, Codex, Claude Code, Windsurf, VS Code, and others.

## What you can do here

With MCP, your coding agent can:

-   **Check costs before and after deploys** – "What's my LLM spend today vs yesterday?" to catch cost regressions
-   **Monitor error rates** – "Are there any LLM errors in the last hour?" to detect issues early
-   **Compare models** – "Compare latency between GPT-4 and Claude for the chat feature" to evaluate model choices
-   **Investigate specific traces** – "Show me the most expensive LLM call from today" to find optimization opportunities

## AI Observability tools

The MCP server provides these tools for working with LLM traces:

| Tool | Description |
| --- | --- |
| get-llm-total-costs-for-project | Get total LLM costs for the project, broken down by model. Useful for monitoring spend and detecting cost anomalies. |
| query-run | Run a custom HogQL query against your LLM trace data. Supports filtering by model, feature, cost, latency, error status, and time range. |

A typical workflow starts with `get-llm-total-costs-for-project` to check overall spend and identify which models are most expensive, then uses `query-run` with a HogQL query to drill into specific traces by feature, time range, or cost threshold.

> **Querying prompts and completions?** The large content fields – `$ai_input`, `$ai_output_choices`, `$ai_input_state`, `$ai_output_state`, and `$ai_tools` – live only on the `posthog.ai_events` table, not `events`. Query `posthog.ai_events` and anchor on `trace_id` to read them. Metadata like model, cost, token counts, and trace IDs stays on `events`. Rows in `posthog.ai_events` are dropped after the [retention period](/docs/ai-observability/data-retention.md) (30 days by default), but rows in `events` have the same retention policy as product analytics events.

## Example prompts

Try these with your MCP-enabled agent:

-   `What are my total LLM costs this week, broken down by model?`
-   `Find the most expensive LLM calls from the last 24 hours.`
-   `Are there any LLM errors today?`
-   `Compare token usage between GPT-4 and Claude for the search feature.`
-   `How has LLM latency changed over the past 7 days?`
-   `Show me traces where a single call cost more than $0.50.`

## Install the MCP server

The recommended way to install is with the [AI wizard](/docs/ai-engineering/ai-wizard.md):

Terminal

PostHog AI

```bash
npx @posthog/wizard mcp add
```

The wizard supports Claude, Cursor, Windsurf, VS Code, and more. You can also [configure it manually](/docs/model-context-protocol.md#get-started-in-30-seconds).

See the [MCP server docs](/docs/model-context-protocol.md) for full setup instructions.

The server also exposes tools for the scoring side of AI Observability – creating and running [evaluations](/docs/ai-evals.md), managing trace reviews and review queues, and configuring [clustering](/docs/ai-observability/clusters.md) – so an agent can set up scoring for you as well as read the results.

## Related

-   Explore the same data in the [web app](/docs/ai-observability/surfaces/web-app.md).
-   Call the same endpoints these tools wrap with the [API](/docs/ai-observability/surfaces/api.md).
-   Learn the [data model](/docs/ai-observability/basics.md) behind traces, spans, and generations.
-   Score traces automatically with [AI Evals](/docs/ai-evals.md).

### Community questions

Ask a question

### Was this page useful?

HelpfulCould be better