MCP server

Query your analytics from an AI agent

Pug’s analytics API, served over the Model Context Protocol: sixteen tools that read, and one that creates and edits dashboards.

One write: dashboards

Sixteen tools read. The seventeenth creates a dashboard or edits one, and can’t delete or share it. There is no tool for erasing a person’s data, and none for sending events.

Your projects, your role

Signed in, the agent reads every project in your orgs and acts with your role in each, so where you are a viewer it only reads. A private key reaches its own project and no other.

The same answers

Tools call the same API as the dashboard, with the same permissions and defaults, so the agent gets the numbers you would see.

Connect

Connect from Claude’s or ChatGPT’s directory, or with one command

It is a hosted endpoint, not a local process, so any MCP client that supports remote servers can connect.

Claude’s apps

Pug is in Claude’s connectors directory. Go to Customize > Connectors, select Discover, search for Pug and select Connect to Claude.

ChatGPT

Pug is in ChatGPT’s plugins. Go to Plugins, search for Pug and select Install plugin.

Claude Code
claude mcp add --transport http pug https://api.pug.sh/mcp
Or a private key, in either header
Authorization: Bearer prv_YOUR_PRIVATE_KEY
x-api-key: prv_YOUR_PRIVATE_KEY
  • Cloud: https://api.pug.sh/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. Signing in also needs PUG_API_BASE_URL set to the API’s public origin and an https PUG_DASHBOARD_BASE_URL; private keys work without either. Claude’s and ChatGPT’s listings connect to Pug Cloud, so add your server by its URL instead: as a custom connector in Claude’s apps, or a custom MCP server in ChatGPT.
  • Signing in needs no key. Connecting from Claude’s directory or installing the ChatGPT plugin signs you in, as does running /mcp in Claude Code after adding the server: click Allow on the Pug page that opens. Other clients can sign in too if they identify themselves with a client ID metadata document; Pug has no dynamic client registration, so a client that registers only that way takes a private key. Settings > AI connections lists each connection and disconnects it, and one unused for 90 days expires.
  • A private key picks the project. It belongs to one project, so there is no project to name in the config. It has no role: whoever holds it can read the project and edit its dashboards. Public keys (pub_) and dashboard logins are refused.
  • Keep the private key out of committed config. It is a server-side credential that reads all of a project’s analytics. Treat it like a database password, not like the public key in your web snippet.
Tools

The seventeen tools

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

Projects

Lists the projects the connection reads. Signed in, the agent calls it first and passes a project’s id to every other tool. A private key already names its project.

  • list_projects

Discovery: before any query

They list the events and properties that 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, sessions and stats. 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_sessions
  • get_profile_stats

Dashboards

List dashboards and read one with its tiles, then create one or edit it: rename it, change its time range, and add, change or remove tiles. An edit carries the version the agent last read, so it fails rather than overwrite a newer change.

  • list_dashboards
  • get_dashboard
  • upsert_dashboard

Compliance

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

  • get_deletion_request

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, managing the project, and deleting or sharing a dashboard are all out of scope too: the one tool that writes creates and edits dashboards, and nothing else.

That tool is marked destructive, so a client that confirms writes, as Claude does, asks before each call unless you chose to always allow it. Tiles a call leaves out stay as they are, a tile goes only when the call names it, and a dashboard with a share link on can’t be edited at all.

The server enforces this. Every tool the API could offer is listed in one place, with 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 because someone forgot to exclude it.

Two credentials open the endpoint. Signing in acts as you, with your current role in each org, and a private key reaches one project. A dashboard login is refused, because it is a full session that can change anything your account can, 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.

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 all bot-tagged comes back with no stats at all.

In practice

What it’s good for

Questions that are faster to ask than to click: whether a funnel moved after a release, what one customer did before the support ticket you are reading, or what changed in a metric before you know which breakdown to look at. The agent looks up which properties your project has and builds the query from those. It can also build the board you would otherwise click together tile by tile, and the server checks each tile’s query before it saves.

It also puts analytics next to your code: the agent that shipped a change can check the event it emits. What an analytics MCP server does has the longer explanation, and the docs have setup for Codex, Cursor, and VS Code.

Connect your agent to Pug.

Create a project, then connect Pug from Claude’s directory or ChatGPT’s plugins, or add it with the command above. Pug Cloud is free up to 100k events a month.

Questions? Email hello@pug.sh