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 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.
Pug is in Claude’s connectors directory. Go to Customize > Connectors, select Discover, search for Pug and select Connect to Claude.
Pug is in ChatGPT’s plugins. Go to Plugins, search for Pug and select Install plugin.
claude mcp add --transport http pug https://api.pug.sh/mcp Authorization: Bearer prv_YOUR_PRIVATE_KEY
x-api-key: prv_YOUR_PRIVATE_KEY - Cloud:
https://api.pug.sh/mcp - Self-hosted:
/mcpon 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 needsPUG_API_BASE_URLset to the API’s public origin and an httpsPUG_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
/mcpin 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.
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_schemaget_insights_property_valuesget_activity_filter_schemaget_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_insightsexplore_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_profileget_profile_by_external_idget_activity_feedget_activity_heatmapget_profile_sessionsget_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_dashboardsget_dashboardupsert_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
What is not a tool
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.
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