MCP server

Ask your analytics a question, from your agent

Pug serves its read-only analytics API as a Model Context Protocol server. Twelve tools, scoped to one project, with no way to write anything.

Shape

What it is, and what it refuses to be

Read-only

Nothing can be created, changed or deleted. There is no tool for erasing a person’s data, and no tool for sending events — the agent can look, and that is all.

One project

A key belongs to one project, and that is the only project the agent can see. There is no project to choose in the config, and no way to reach a different one.

The same answers

Tools run through the same API the dashboard uses, so an agent sees exactly what you would see: the same permissions, the same defaults, the same numbers.

Connect

One command, one key

It is a hosted endpoint rather than something you install and run locally, so any MCP client that supports remote servers can connect.

Claude Code

claude mcp add --transport http pug https://api.pugs.dev/mcp \
  --header "Authorization: Bearer prv_YOUR_PRIVATE_KEY"

Either header works

Authorization: Bearer prv_YOUR_PRIVATE_KEY
x-api-key: prv_YOUR_PRIVATE_KEY

Cloud: https://api.pugs.dev/mcp
Self-hosted: /mcp on the same host and port as the rest of your API — the endpoint is part of the server, not a separate service.
The key picks the project. A private key belongs to one project, so there is no project to name in the config. Public keys (pub_) and dashboard logins are refused.
Keep the private key out of committed config. It is a server-side credential with read access to all of a project’s analytics — treat it like a database password, not like the public key in your web snippet.

Tools

The twelve tools

Grouped the way the server tells an agent to use them: discover what exists, then ask a project-wide question or look up one person.

Discovery — call these first

They report which events and properties actually exist in your project. Without them an agent guesses a name, gets an empty result, and reports it as a finding.

get_insights_filter_schema
get_insights_property_values
get_activity_filter_schema
get_activity_property_values

Project-wide questions

One tool covers the analysis: trends, funnels, retention, segmentation, user flow, top lists and a metric per country. The other pages through raw events, filter by filter.

query_insights
explore_events

One person at a time

Look a person up by their Pug id or by the id your own application gave them, then read their timeline. These describe one person and cannot answer project-wide questions.

get_profile
get_profile_by_external_id
get_activity_feed
get_activity_heatmap
get_profile_stats

Compliance

Read the status of a data-erasure request that was already submitted. Submitting or performing one is not available here.

get_deletion_request

Safety

What is deliberately not a tool

The interesting part of an agent-facing API is the surface it withholds.

Erasing a person’s data is permanent, so it is not something an agent can do. It is left out of the tool list on purpose and stays a deliberate human action through the API. Sending events, changing identities and managing the project are all out of scope too: this endpoint reads, and does nothing else.

That is enforced rather than promised. Every tool the API could offer is listed in one place with either the name it is published under or the reason it is held back, and the server refuses to start if anything appears that is not on the list. A dangerous tool cannot reach an agent by somebody forgetting to exclude it.

Only a private key opens the endpoint. A dashboard login is refused, because it would widen access from one project to your whole account, and the public key from your website snippet is refused because anyone can read it out of your page. There is no setting that changes either of those.

One thing worth knowing before you read an answer: the defaults are the dashboard’s defaults. Automated traffic is excluded from every metric unless you ask for it, so a visitor whose activity is entirely bot-tagged comes back with no stats at all.

In practice

What it is actually good for

The useful pattern is not “replace the dashboard”. It is the questions that are faster to ask than to click: checking whether a funnel moved after a release, pulling one customer’s timeline while reading their support ticket, or asking what changed in a metric without first deciding which breakdown to look at. The agent can look up which properties your project actually has and build the query from those — which is the step that usually stops someone from asking at all.

It is also how the analytics gets into the loop while you are writing code: the same agent that just shipped a change can read what happened to the event it emits. If you are new to the protocol, what an analytics MCP server actually does is the longer explanation, and the docs carry per-client setup for Codex, Cursor and VS Code.

Point your agent at your own data

Create a project, copy a private key, and connect it in one command. Free during open beta, and self-hostable under AGPL-3.0.

Start free

Questions? Email hello@pug.sh