> AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt

# Use AI Observability over PostHog MCP

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.

## Before you start

1.  **Set up AI Observability** – [install a PostHog LLM SDK or provider integration](/docs/ai-observability/installation.md) so traces are captured.
2.  **Connect the MCP server** – [install it in your AI tool](#install-the-mcp-server) and give it access to your project.

## 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 ships tools for every part of AI Observability. This list is generated from the [PostHog repo](https://github.com/PostHog/posthog/blob/master/services/mcp/schema/tool-definitions-all.json) at build time, so it stays current as tools ship:

Traces – Find traces and read a single trace end to end

-   query-llm-trace
-   query-llm-traces-list

Costs – Project-wide and per-user LLM spend

-   get-llm-total-costs-for-project
-   llma-personal-spend

Evaluations – Create, run, and manage evaluations, reports, and directories

-   llma-evaluation-backfill-cancel
-   llma-evaluation-backfill-create
-   llma-evaluation-backfill-estimate
-   llma-evaluation-backfill-get
-   llma-evaluation-backfill-list
-   llma-evaluation-config-get
-   llma-evaluation-config-set-active-key
-   llma-evaluation-create
-   llma-evaluation-delete
-   llma-evaluation-directory-create
-   llma-evaluation-directory-delete
-   llma-evaluation-directory-get
-   llma-evaluation-directory-list
-   llma-evaluation-directory-update
-   llma-evaluation-get
-   llma-evaluation-judge-models
-   llma-evaluation-list
-   llma-evaluation-report-create
-   llma-evaluation-report-generate
-   llma-evaluation-report-get
-   llma-evaluation-report-list
-   llma-evaluation-report-run-list
-   llma-evaluation-report-update
-   llma-evaluation-run
-   llma-evaluation-test-hog
-   llma-evaluation-update

Datasets – Curate datasets and dataset items

-   llma-dataset-archive
-   llma-dataset-create
-   llma-dataset-get
-   llma-dataset-item-archive
-   llma-dataset-item-create
-   llma-dataset-item-get
-   llma-dataset-item-list
-   llma-dataset-item-restore
-   llma-dataset-item-update
-   llma-dataset-item-version-list
-   llma-dataset-list
-   llma-dataset-restore
-   llma-dataset-revision-list
-   llma-dataset-update

Review queues – Human review queues and their items

-   llma-review-queue-create
-   llma-review-queue-delete
-   llma-review-queue-get
-   llma-review-queue-item-create
-   llma-review-queue-item-delete
-   llma-review-queue-item-get
-   llma-review-queue-item-list
-   llma-review-queue-item-update
-   llma-review-queue-list
-   llma-review-queue-update

Clustering – Configure clustering jobs and read their results

-   llma-clustering-config-get
-   llma-clustering-config-set-event-filters
-   llma-clustering-job-create
-   llma-clustering-job-delete
-   llma-clustering-job-get
-   llma-clustering-job-list
-   llma-clustering-job-update

Prompts – Manage prompts and prompt labels

-   llma-prompt-create
-   llma-prompt-duplicate
-   llma-prompt-get
-   llma-prompt-label-delete
-   llma-prompt-label-set
-   llma-prompt-list
-   llma-prompt-update

Trace reviews – Structured reviews attached to traces

-   llma-trace-review-create
-   llma-trace-review-delete
-   llma-trace-review-get
-   llma-trace-review-list
-   llma-trace-review-update

Score definitions – Define and version custom scores

-   llma-score-definition-create
-   llma-score-definition-get
-   llma-score-definition-list
-   llma-score-definition-new-version
-   llma-score-definition-update
-   llma-score-definition-version-get
-   llma-score-definition-version-list

Taggers – Auto-tag generations with Hog-based taggers

-   llma-tagger-create
-   llma-tagger-list
-   llma-tagger-test-hog

Provider keys – LLM provider keys used by evaluations

-   llma-provider-key-get
-   llma-provider-key-list

Custom parsers – Parser recipes for custom LLM event formats

-   llma-parser-recipe-create
-   llma-parser-recipe-reference

Summarization – AI trace summarization

-   llma-summarization-create

Other

-   llma-offline-experiment-complete
-   llma-offline-experiment-create
-   llma-offline-experiment-fail
-   llma-offline-experiment-get
-   llma-offline-experiment-item-get
-   llma-offline-experiment-item-list
-   llma-offline-experiment-item-payload-get
-   llma-offline-experiment-item-result-list
-   llma-offline-experiment-list
-   llma-offline-experiment-result-cells
-   llma-offline-experiment-result-payload-get
-   llma-offline-experiment-scorer-summary-list
-   llma-offline-experiment-upload
-   llma-offline-scorer-history

A typical workflow starts with `query-llm-traces-list` to find relevant traces, `query-llm-trace` to inspect one end to end, and `get-llm-total-costs-for-project` or `execute-sql` to aggregate costs and answer custom questions.

> **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):

### Install the PostHog MCP

[Learn more](/docs/model-context-protocol.md)

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

Supports Next.js, React, Python, and 24 more

Claude

Cursor

VS Code

Windsurf

Codex

Zed

Lovable

Replit

v0

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

-   Teach your agent how to use these tools with [skills](/docs/ai-observability/skills.md).
-   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).

### Still have questions?

Ask PostHog AI

### Was this page useful?

HelpfulCould be better