Pug
Запрашивайте аналитику продукта Pug (тренды, воронки, удержание, события и профили пользователей) и создавайте дашборды. Подключайтесь, войдя через OAuth или используя приватный API-ключ.
Размещённый MCP-сервер
npx add-mcp 'https://api.pug.sh/mcp'Устанавливается в Claude Code, Codex, Cursor и другие
Документация
Pug serves its analytics API as a Model Context Protocol server at /mcp, so an agent can answer questions about your product’s data (run an insight, browse the raw event stream, look up one user) without you writing the query. Sixteen of its seventeen tools read; upsert_dashboard creates and edits dashboards.
The endpoint is a thin adapter, not a second API: every tool call is replayed through the same Connect handlers an HTTP request hits, so validation, authentication and authorization behave identically. Anything the Insights, Profiles or Activity services refuse over HTTP, they refuse here.
Use with Claude connectors
Pug is listed in Claude’s connectors directory, so Claude’s apps (claude.ai, Desktop and mobile) need no URL or config file. Each person connects Pug from the directory and signs in to it.
Pro, Max and other individual plans
- In Claude, go to Customize > Connectors and select Discover.
- Search for
Pugand open its listing, or go straight to claude.ai/directory/pug. - Select Connect to Claude.
- A Pug page opens. Sign in if asked, review the projects Claude will read and click Allow, and you are back in Claude.
Team and Enterprise plans
An Owner opens Pug’s listing and selects Connect for your team, which adds Pug for the whole organization. Each member then selects Connect to Claude there and approves the connection on Pug’s page with their own account, as in step 4 above. Until an Owner adds Pug, members see Request, or a note to ask an Owner, in place of the connect button.
Every connection belongs to one person and acts with their role, so removing someone from a Pug org cuts their connection off from it at their next call. Disconnecting in Claude leaves the connection listed in Pug until it expires, so remove it under Settings > AI connections as well.
As a custom connector
The directory listing connects to Pug Cloud. To connect Claude to a self-hosted server, or with a private key, add Pug by its URL:
- In Claude, go to Customize > Connectors.
- Click + Add, then Add custom connector.
- Name it
Pug, the name your connector list shows. - Paste your server’s
/mcpURL, orhttps://api.pug.sh/mcpfor Pug Cloud, and click Continue. - Claude detects Pug’s sign-in. Keep Sign in now, and Use Claude’s published identity as the OAuth client, then click Add and approve the connection on Pug’s page.
On Team and Enterprise plans, an Owner adds it under Organization settings > Connectors: click Add, hover over Custom, select Web and continue from step 3. Members then find Pug under Customize > Connectors, marked Custom, and click Connect.
Keep Use Claude’s published identity: Pug recognizes Claude by the metadata document Anthropic publishes and has no dynamic client registration, so the other two OAuth client choices fail. If your dialog shows Advanced settings instead, leave the OAuth client ID and secret empty.
With a private key
Choosing No sign in in step 5 connects with a private key instead. Add it under Request headers, picking x-api-key and pasting the key on its own:
| Header | Value |
|---|---|
x-api-key | prv_YOUR_PRIVATE_KEY |
A request header is stored on the connector, not on a person, so everyone who can use that connector shares one key: they read the same project and can edit its dashboards, whatever their role in Pug, and revoking the key disconnects all of them at once. That suits a team that wants one project without each person needing a Pug account; it is not a way to give each person their own scope.
Claude can’t change a connector’s authentication once it is added. To move one that uses a key over to sign-in, remove it and add it again.
Use with ChatGPT
Pug is listed in ChatGPT’s plugins, so ChatGPT needs no URL. Each person installs Pug and signs in to it:
- In ChatGPT, go to Plugins and search for
Pug, or go straight to its listing. - Select Install plugin.
- When ChatGPT sends you to Pug, sign in if asked, review the projects ChatGPT will read and click Allow.
Removing the plugin in ChatGPT leaves the connection listed in Pug until it expires, so remove it under Settings > AI connections as well.
As a custom MCP server
The listing connects to Pug Cloud. To connect ChatGPT to a self-hosted server, add Pug by its URL, from ChatGPT on the web:
- Go to Plugins, select Add, then Add custom MCP server.
- Name it
Pug, enter your server’s/mcpURL, orhttps://api.pug.sh/mcpfor Pug Cloud, and choose OAuth, leaving any client ID and secret empty. - Accept the risk warning, select Create as a plugin, then install it.
- When ChatGPT sends you to Pug, sign in if asked, review the projects ChatGPT will read and click Allow.
Endpoint
| Environment | URL |
|---|---|
| Pug Cloud | https://api.pug.sh/mcp |
| Self-hosted / local | http://localhost:3000/mcp |
Use api.pug.sh even though the HTTP API is at api.pugs.dev. Both hosts reach the same server and a private key works at either, but signing in works only at api.pug.sh, the host that issues the tokens.
Transport is streamable HTTP in stateless mode, with no stdio bridge, so your client needs remote-server support. Both /mcp and /mcp/ are served, so a trailing slash from an ingress or a pasted URL is fine.
Every reply comes back on the POST as JSON. The spec’s optional standalone SSE stream (GET /mcp) is refused with 405, since a stateless server has no session for it to attach to. Clients that treat that stream as optional, as the ones on this page do, are unaffected.
Authentication
/mcp takes one of two credentials. Signing in acts as you in every project of your orgs and needs no key. A private key reaches its own project, for clients that can’t sign in.
Sign in
A client that supports MCP sign-in (OAuth) and identifies itself with a client ID metadata document, as Claude’s apps, Claude Code and ChatGPT do, needs only the URL. It opens a Pug page where you sign in if asked, see the projects it will read, and click Allow. Pug offers no dynamic client registration, so a client that registers only that way needs a private key instead.
The connection reads every project in the orgs you belong to when you approve it, including projects added to them later, for as long as you stay in each org. An org you join, or leave and rejoin, after approving isn’t included until you connect again. The connection acts with your current role in each org: where you are a viewer it only reads, and where you are a member or an admin it can also create and edit dashboards. There is no key to store or leak.
Pug lists every connection under Settings > AI connections, with its orgs and when it was last used. Disconnect one there and the client’s next call fails. A connection unused for 90 days expires, after which the client asks you to sign in again.
Private key
A client that can’t sign in sends a private key, either way:
Authorization: Bearer prv_YOUR_PRIVATE_KEY
x-api-key: prv_YOUR_PRIVATE_KEY
Use whichever your client makes easy. If a request carries both, x-api-key wins.
The key names its project, so the config carries no project ID: list_projects returns that project alone, and a call naming any other is refused. A key has no role, so whoever holds it reads the project and can create and edit its dashboards. Public keys (pub_...) and dashboard JWTs are both rejected with 401. See Authentication for where keys live.
Connect a client
Claude Code logged in with a Claude account picks up that account’s connectors, so if you connected Pug in Claude’s apps, /mcp already lists it and there is nothing to add. Otherwise add it yourself:
claude mcp add --transport http pug https://api.pug.sh/mcp
Then run /mcp inside Claude Code, or claude mcp login pug in your shell, and sign in when your browser opens. /mcp also confirms the server connected and lists its tools. The token never lands in .mcp.json, so --scope project can share the server with your team, and each person signs in as themselves.
To use a private key instead:
claude mcp add --transport http pug https://api.pug.sh/mcp \
--header "Authorization: Bearer prv_YOUR_PRIVATE_KEY"
That writes to your own local config. With --scope project it would write the key into the repo’s .mcp.json, which gets committed: use an environment variable there, or keep the default scope.
codex mcp add pug --url https://api.pug.sh/mcp \
--bearer-token-env-var PUG_PRIVATE_KEY
Or write it into ~/.codex/config.toml, or .codex/config.toml for a single trusted project:
[mcp_servers.pug]
url = "https://api.pug.sh/mcp"
bearer_token_env_var = "PUG_PRIVATE_KEY"
Codex sends that variable’s value as Authorization: Bearer .... There is no inline token field (a literal key in the config is rejected), so export PUG_PRIVATE_KEY before launching Codex.
In ~/.cursor/mcp.json (global) or .cursor/mcp.json (this project only):
{
"mcpServers": {
"pug": {
"url": "https://api.pug.sh/mcp",
"headers": {
"Authorization": "Bearer ${env:PUG_PRIVATE_KEY}"
}
}
}
}
Cursor resolves ${env:...} from the environment it was launched with, so export PUG_PRIVATE_KEY in your shell profile rather than pasting the key here.
In .vscode/mcp.json. The inputs entry makes VS Code prompt for the key once and store it itself, so nothing secret lands in the file:
{
"inputs": [
{
"type": "promptString",
"id": "pug-private-key",
"description": "Pug private API key",
"password": true
}
],
"servers": {
"pug": {
"type": "http",
"url": "https://api.pug.sh/mcp",
"headers": {
"Authorization": "Bearer ${input:pug-private-key}"
}
}
}
}
A client that can sign in needs only the URL. Anything else that speaks streamable HTTP and can set a request header works with a private key: point it at https://api.pug.sh/mcp and add Authorization: Bearer prv_....
To check the URL and key without a client, ask the server for its tool list. The endpoint is stateless, so this works with no prior handshake:
curl -X POST https://api.pug.sh/mcp \
-H "Authorization: Bearer prv_YOUR_PRIVATE_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
A healthy response lists every tool with its description and input schema. 401 means the credential was refused; check the prv_ prefix and that the key has not been revoked. 400 with a complaint about Accept means that header is missing a half: it must offer both application/json and text/event-stream, even though the reply comes back as JSON.
The server ships its own guidance to the agent at initialize, so a client that surfaces MCP instructions already knows to call list_projects first, to discover the schema before querying, which tools are project-wide and which describe one user, and to remove a dashboard tile only when you ask.
Tools
Every tool but list_projects works in one project, named by its project_id argument. With a key it is optional, since the key names its project. With a sign-in every call needs it, and a call without one is refused with a message naming list_projects. The server describes each tool to the agent itself; in outline:
| Group | Tools | What the agent can do |
|---|---|---|
| Projects | list_projects | List the projects the connection reads, each with its org |
| Discovery | get_insights_filter_schema, get_insights_property_values, get_activity_filter_schema, get_activity_property_values | List the event kinds and property keys that exist, and the values seen for one key, so a query names real ones |
| Project-wide | query_insights, explore_events | Run trends, funnels, retention, segmentation, user flows, top-K and maps (the Insights API spec), or page through the raw event stream |
| One user | get_profile, get_profile_by_external_id, get_activity_feed, get_activity_heatmap, get_profile_sessions, get_profile_stats | Look a profile up by its Pug id or by the external_id your application assigned, then read that user’s activity feed, daily heatmap, sessions and stats |
| Dashboards | list_dashboards, get_dashboard, upsert_dashboard | List dashboards and read one with its tiles, then create a dashboard or edit one: rename it, change its time range, and add, change or remove tiles |
| Compliance | get_deletion_request | Report the status of an erasure request someone already submitted |
upsert_dashboard is the only tool that writes. An edit needs the dashboard’s update_time, from get_dashboard or the last upsert_dashboard, and fails rather than overwrite a change made since. Tiles the call leaves out stay as they are, and a tile goes only when the call lists it for removal. It can’t delete or share a dashboard, or edit one that has a share link on. Dashboards can’t show segmentation insights or session metrics, markdown tiles can’t contain images, and a dashboard holds at most 100 tiles.
upsert_dashboard is marked destructive, so Claude asks you before each call unless you choose to always allow it.
The tools/list request under Any other client above returns each tool’s description and input schema.
What is deliberately not exposed
The tool surface is a curated subset, not everything the API can do:
- Profile erasure (
Delete,DeleteDataSubject): GDPR/DPDP erasure is irreversible, so it stays a human action through the Profiles API, never an LLM-callable tool.get_deletion_requestonly reads the status of a request someone already submitted. SegmentUsers: the drill-down insight is still in progress; it is served as a Connect RPC but held off the tool surface until it lands.List(profiles): server-streaming, which MCP tools do not model. Useexplore_eventsor a profile lookup instead.- Everything under
sdk.*anddashboard.*: ingest, identity and management are out of scope, deleting and sharing dashboards included.
The exposed set is pinned in the server: a generated tool with no policy entry, or a policy entry with no matching tool, fails startup rather than shipping a surprise tool. Renaming an RPC upstream breaks the build, not your agent.
Limits and errors
- Two minutes per tool call. A wide
query_insightsover a long window is the one that will hit it; narrow the time range or the breakdown. - Time-range caps by granularity apply exactly as they do on the Insights API: the same handler enforces them.
- Errors are Connect errors. A rejected argument comes back as
invalid_argumentnaming the field, an unknown profile asnot_found, a project the credential can’t read asunauthenticated, a viewer’s dashboard edit aspermission_denied, and a stale edit or one to a dashboard with a share link on asfailed_precondition. See the error model. - A failed tool returns the whole error as JSON:
code,messageand thedetailsarray. The correlation id is in there, as agoogle.rpc.RequestInfo; quote it in a support request.
Self-hosting
/mcp is mounted on every Pug deployment and takes private keys with no configuration, on the same host and port as the rest of the API (3000 by default, see Configuration).
Signing in stays off until you set PUG_API_BASE_URL to the API’s public origin, such as https://api.example.com. It takes no path, because the sign-in metadata sits at the root of that host. PUG_DASHBOARD_BASE_URL must then be https too, since the dashboard serves the page where people approve a connection, or the server won’t start. Either may be http on localhost or 127.0.0.1. Claude’s apps and ChatGPT reach your server from Anthropic’s and OpenAI’s infrastructure, so they need a public URL; Claude Code connects from your own machine, so PUG_API_BASE_URL=http://localhost:3000 is enough to try sign-in locally.
Pug fetches each client’s metadata document over outbound HTTPS, ignoring any proxy, so signing in needs direct outbound access. get_dashboard and upsert_dashboard link each dashboard under PUG_DASHBOARD_BASE_URL, and return no link while it is unset.
Behind a reverse proxy, pass /mcp through, plus /oauth/token and /.well-known/oauth-* once sign-in is on, and keep the Authorization header across the hop. A proxy that strips it is the usual cause of a server that connects from localhost but answers 401 in production.
Further reading
- Insights API: the query spec behind
query_insights - Profiles API: profile lookups and erasure over HTTP
- Authentication: issuing and revoking private keys
- API overview: headers, base URLs and the Connect error model