Skip to content
Getting started

Agents, skills and MCP

How AI assistants and coding agents set up and use Product Metrics, with the MCP server, the productmetrics CLI, skills and the docs MCP.

This page is for using Product Metrics through AI: an assistant such as Claude or ChatGPT that answers questions about your store and campaigns, or a coding agent that runs the setup for you from the terminal.

PathHowFor
MCP serverhttps://www.productmetrics.io/mcpClaude, ChatGPT, Cursor: analyse Google Ads, POAS and stock, and run setup
CLIproductmetricsCoding agents and scripts: setup, checks, --json output
SkillsSkills tabTeach the agent the real steps for a task
Docs MCPhttps://www.productmetrics.io/docs/api/mcpSearch these docs while the agent works
llms.txthttps://www.productmetrics.io/docs/llms.txtOne index of every docs page

The app, the CLI, the MCP server and the API all work on the same workspace: see Set up from the app, CLI, MCP or API.

MCP server

The Product Metrics MCP server gives an assistant your own data: the properties you can open, your Google Ads account live, and your store’s margins, stock and orders.

https://www.productmetrics.io/mcp

Sign-in is OAuth. Add the URL as a custom connector, sign in to Product Metrics in your browser and click Allow. There is no API key to copy.

  • One connection covers every workspace you can open.
  • Steps per client are in Connect your assistant.
  • From the terminal, productmetrics mcp-config --client claude|chatgpt|cursor prints them.

The server has two kinds of tools:

ToolsWhat they do
Analysis toolslist_properties, explain_google_ads_change, get_google_ads_report, get_poas_report, get_google_ads_changes, get_store_overview and more. They read only; propose_change files a proposal a person approves in Priorities. Full list: MCP tools.
Code Mode: search and executeThe whole Product Metrics API in two tools. search runs code against the API’s OpenAPI document to find an operation. execute runs code that calls it for you: setup status, connecting Google Ads and stores, conversion actions, settings.

Code Mode follows the same rules as the CLI and the API:

  • execute needs the read, setup and write access the consent page shows. A connection with MCP access only can use the analysis tools.
  • Operations that delete something run only after you agree.
  • A step that needs you in a browser (Google consent, the Shopify install, checkout) comes back as a link. The assistant gives it to you, waits, then reads the setup status again.
  • Secret fields, such as a store setup token, never reach the assistant. They show only in the Product Metrics app or the CLI.
  • One run makes at most 25 requests, each counted against your rate limit.

Ask in plain language:

"What is left to set up in Product Metrics?"
→ execute (GET /setup/status)

"Why did my Google Ads ROAS drop last week?"
→ list_properties, then explain_google_ads_change

"Which products lose money after ads?"
→ get_poas_report (level: product, only_unprofitable: true)

CLI

productmetrics calls the same API from the terminal. Every API operation is a command, productmetrics <group> <command>, and its flags are the operation’s fields. The command list comes from the server, so new operations work without a new release.

# install (Node.js 22 or later), or run once with npx @productmetrics/cli
npm install -g @productmetrics/cli

# sign in in the browser
productmetrics login

# the short guide for AI agents
productmetrics help agents

# find an operation
productmetrics capabilities --search status

productmetrics setup get-status \
  --company-id <company_id> \
  --json

What an agent needs to know:

  • Pass --json. stdout then holds exactly one JSON document (shapes below). --select '.data.properties[].property_id' prints only part of it.
  • No prompts. Without a terminal, or with PM_AGENT=1, CI or --no-input, productmetrics never prompts, never opens a browser and prints no colours.
  • Discover, never guess. productmetrics <group> <command> --help --json gives the exact flags, types and allowed values. Ids come from earlier results.
  • Retries are safe where --help lists --auto-idempotency-key (companies create, stores connect, tracking update-margin-policy). After any other failed write, read the state before retrying. --dry-run prints the request without sending it.
  • Deletes need --yes. Ask the person first.

Signing in needs a person in a browser. When productmetrics status --json shows signed_in: false, the agent asks you to run productmetrics login in your own terminal. In CI, set PM_TOKEN.

More in CLI for agents and JSON and exit codes.

Skills

Skills are task instructions an agent loads when it needs them: which tools to call, in which order, and what to check. Product Metrics publishes skills for setting up tracking, connecting Google Ads, checking tracking, bidding on profit and analysing Google Ads.

The index for agents is at:

https://www.productmetrics.io/docs/.well-known/agent-skills/index.json

See Skills for what each one does and Install skills to add them to your agent.

For a coding agent, use all three together: a skill for the task, productmetrics for the commands, and the docs MCP for the details.

Docs MCP

A remote MCP server that lets the agent search these docs while it works. It reads documentation only: for your own data, use the MCP server above.

https://www.productmetrics.io/docs/api/mcp
claude mcp add --transport http product-metrics-docs \
  https://www.productmetrics.io/docs/api/mcp

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "product-metrics-docs": {
      "url": "https://www.productmetrics.io/docs/api/mcp"
    }
  }
}
codex mcp add product-metrics-docs \
  --url https://www.productmetrics.io/docs/api/mcp

Add to .vscode/mcp.json:

{
  "servers": {
    "product-metrics-docs": {
      "type": "http",
      "url": "https://www.productmetrics.io/docs/api/mcp"
    }
  }
}

llms.txt

https://www.productmetrics.io/docs/llms.txt lists every docs page with its title and one-line description. Point an agent at it before it reads further, so it finds the right page instead of guessing.

Starter prompt

Paste this into your coding agent to set up Product Metrics:

You are setting up Product Metrics for my store.

- Read https://www.productmetrics.io/docs/llms.txt (or use the
  product-metrics-docs MCP) before you act.
- Use the productmetrics CLI with --json. Run `productmetrics help agents` first, then
  `productmetrics status --json`. If I am not signed in, ask me to run
  `productmetrics login` in my own terminal.
- Read the setup state with
  `productmetrics setup get-status --company-id <id> --json` and follow
  hub.company.next_action and hub.property.next_action, one step
  at a time.
- Never guess a command or flag: run
  `productmetrics <group> <command> --help --json`. Ids come from earlier
  results.
- Exit code 4 means I must finish a step: give me next_action.url
  (or the store setup token) and wait for me.
- Pass --auto-idempotency-key where --help lists it. Ask me before
  anything that needs --yes.
- Never ask me for a password or an API key; ask me for store
  credentials only when a step needs them.

Where next