> ## Documentation Index
> Fetch the complete documentation index at: https://82616d6-productmetrics.manicule.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
> For every page in one file, fetch https://82616d6-productmetrics.manicule.dev/docs/llms-full.txt (large).
> To search and read these docs as tools, connect the MCP server at https://82616d6-productmetrics.manicule.dev/docs/api/mcp.
> Every agent surface: https://82616d6-productmetrics.manicule.dev/docs/.well-known/llms-manifest.json

# Agents, skills and MCP (/docs/overview/agents-skills-and-mcp)

<!-- agent-signals: reading_time_min: 7 · est_tokens: 2539 · updated: 2026-11-16 -->
Related: [Should I use Product Metrics?](/docs/overview/comparison.md), [What is Product Metrics?](/docs/overview/what-is-product-metrics.md), [Stores and tracking API](/docs/api/stores-and-tracking.md)

> 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.

| Path           | How                                           | For                                                                        |
| -------------- | --------------------------------------------- | -------------------------------------------------------------------------- |
| **MCP server** | `https://www.productmetrics.io/mcp`           | Claude, ChatGPT, Cursor: analyse Google Ads, POAS and stock, and run setup |
| **CLI**        | `productmetrics`                              | Coding agents and scripts: setup, checks, `--json` output                  |
| **Skills**     | [Skills tab](/docs/agent-skills/overview)          | Teach the agent the real steps for a task                                  |
| **Docs MCP**   | `https://www.productmetrics.io/docs/api/mcp`  | Search these docs while the agent works                                    |
| **llms.txt**   | `https://www.productmetrics.io/docs/llms.txt` | One 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](/docs/using/overview).

## 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.

```text
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](/docs/mcp/connect).
* From the terminal, `productmetrics mcp-config --client claude|chatgpt|cursor` prints them.

The server has two kinds of tools:

| Tools                                 | What they do                                                                                                                                                                                                                                                                    |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Analysis tools**                    | `list_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](/docs/mcp/tools). |
| **Code Mode: `search` and `execute`** | The 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:

```text
"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.

```bash
# 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.



**JSON output and exit codes**

With `--json`, stdout holds one of these two shapes:

```text
{ "ok": true, "data": …, "request_id": … }

{ "ok": false, "error": { "code", "message", "hint" }, "exit_code": n }
```

| Exit code | Meaning                                                                                 |
| --------- | --------------------------------------------------------------------------------------- |
| `0`       | OK                                                                                      |
| `1`       | The API answered with an error (code, message, request id and hint on stderr).          |
| `2`       | Usage error: unknown command, flag or value, a missing value, a delete without `--yes`. |
| `3`       | Not signed in, the token was refused, or it lacks the scope.                            |
| `4`       | A person must finish a step in a browser: the URL is in `next_action.url`.              |

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](/docs/cli/for-agents) and [JSON and exit codes](/docs/cli/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:

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

See [Skills](/docs/agent-skills/overview) for what each one does and [Install skills](/docs/agent-skills/install) to add them to your agent.



> **Note:** 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](#mcp-server) above.

```text
https://www.productmetrics.io/docs/api/mcp
```



**Claude Code**

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

**Cursor**

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "product-metrics-docs": {
      "url": "https://www.productmetrics.io/docs/api/mcp"
    }
  }
}
```

**Codex**

```bash
codex mcp add product-metrics-docs \
  --url https://www.productmetrics.io/docs/api/mcp
```

**VS Code**

Add to `.vscode/mcp.json`:

```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:

```text
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



* [Quickstart](/docs/quickstart): every setup step with the CLI, MCP and API.
* [Connect your assistant](/docs/mcp/connect): Claude, ChatGPT, Claude Code and Cursor.
* [CLI for agents](/docs/cli/for-agents): driving `productmetrics` from a coding agent.
* [Skills](/docs/agent-skills/overview): task instructions for your agent.
