> ## Documentation Index
> Fetch the complete documentation index at: https://dc9c767-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://dc9c767-productmetrics.manicule.dev/docs/llms-full.txt (large).
> To search and read these docs as tools, connect the MCP server at https://dc9c767-productmetrics.manicule.dev/docs/api/mcp.
> Every agent surface: https://dc9c767-productmetrics.manicule.dev/docs/.well-known/llms-manifest.json

# Product Metrics in Codex (/docs/integrations/codex)

<!-- agent-signals: reading_time_min: 6 · est_tokens: 2601 · updated: 2026-11-16 -->
Related: [Product Metrics in Claude](/docs/integrations/claude.md), [Product Metrics in ChatGPT](/docs/integrations/chatgpt.md), [Product Metrics in Claude Code](/docs/integrations/claude-code.md), [Product Metrics in Cursor](/docs/integrations/cursor.md)

> Add the Product Metrics MCP server, skills and productmetrics CLI to the OpenAI Codex CLI, then set up tracking and analyse Google Ads from the terminal.

The [OpenAI Codex CLI](https://github.com/openai/codex) works with Product Metrics in three ways:

* **MCP server** (`https://www.productmetrics.io/mcp`): reads your stores, products and Google Ads account, and runs setup through the API.
* **Skills**: give Codex the exact steps for tasks such as setting up tracking.
* **`productmetrics` CLI**: Codex runs it with JSON output.

You sign in in your browser. There is no API key.

## Install

### 1. Add the MCP server

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

Or add it to `~/.codex/config.toml` by hand:

```toml title="~/.codex/config.toml"
[mcp_servers.product-metrics]
url = "https://www.productmetrics.io/mcp"
```

### 2. Install the skills

From the project where you run Codex:

```bash
npx skills add https://www.productmetrics.io/docs \
  --skill '*' \
  --agent codex \
  -y
```

This installs `set-up-tracking`, `connect-google-ads`, `check-tracking`, `bid-on-profit` and `analyse-google-ads`. Add `--global` to install them for every project. Needs Node.js 22.20 or later. See [Install skills](/docs/agent-skills/install).

### 3. Install the productmetrics CLI (optional)

Install it from npm (Node.js 22 or later), then check it:

```bash
npm install -g @productmetrics/cli
productmetrics --version
```

To run it once without installing, use `npx @productmetrics/cli` in place of `productmetrics`. Codex runs `productmetrics` like any other command.

Restart Codex after installing.

## Authenticate

**MCP server.** Sign in once from your terminal:

```bash
codex mcp login product-metrics
```

Your browser opens the Product Metrics consent page. Check what Codex **Can read** and **Can change**. Signed out, click **Continue with Google** (it creates an account if you have none) or **Sign in** under the card: either brings you back to the same page. Then click **Connect Codex**.

**productmetrics CLI.** Run this in your own terminal, not through Codex:

```bash
# opens the browser and waits up to 5 minutes
productmetrics login
# which API, signed in or not, scopes, expiry
productmetrics status
```

So that `productmetrics` never prompts or opens a browser when Codex runs it, set `PM_AGENT=1`:



**macOS / Linux (zsh)**

```bash
echo 'export PM_AGENT=1' >> ~/.zshrc
source ~/.zshrc
```

**macOS / Linux (bash)**

```bash
echo 'export PM_AGENT=1' >> ~/.bashrc
source ~/.bashrc
```

**Windows (PowerShell)**

```powershell
[System.Environment]::SetEnvironmentVariable("PM_AGENT", "1", "User")
```

Restart your terminal after running this.

## How it works

* **Analysis tools read live.** `list_properties` picks the store, then tools such as `explain_google_ads_change`, `get_google_ads_report` and `get_poas_report` read your Google Ads account and your store's margins and stock. They never change Google Ads or your store.
* **Setup runs through Code Mode.** `search` finds an API operation; `execute` runs code that calls it: setup status, connecting stores and Google Ads, creating conversion actions. Operations that delete something run only after you confirm.
* **Browser steps come back as a link.** Google consent, a store install or checkout needs you in a browser. Codex gives you the link, waits, then reads the setup status again. With the CLI, `productmetrics` exits `4` and puts the URL in `next_action.url`.
* **Skills load on demand.** Codex reads a skill when your request matches its description.
* **The CLI speaks JSON.** Codex runs `productmetrics help agents` first, then passes `--json` to every command and reads exactly one JSON document from stdout.
* **Secrets stay out of the chat.** Fields such as a store setup token never reach the assistant through MCP. `productmetrics` hides them unless you pass `--show-secrets`.

## Skills and tools

### Skills

| Skill                | What it does                                                                                 |
| -------------------- | -------------------------------------------------------------------------------------------- |
| `set-up-tracking`    | Server-side conversion tracking end to end: workspace, store, Google Ads, conversion actions |
| `connect-google-ads` | Connect a Google Ads account and its Merchant Center, or fix a connection                    |
| `check-tracking`     | Check the store, the conversion actions, Enhanced Conversions and the latest purchase        |
| `bid-on-profit`      | Set up and check POAS or ROAS bidding in Google Ads and Meta                                 |
| `analyse-google-ads` | Explain changes, wasted spend and POAS, read-only                                            |

### MCP tools

| Tool                           | Description                                                     |
| ------------------------------ | --------------------------------------------------------------- |
| `list_properties`              | The stores (properties) you can open; call first                |
| `get_store_overview`           | The store's own sales, orders and profit next to the ads        |
| `explain_google_ads_change`    | Why a Google Ads metric changed, in one call                    |
| `get_google_ads_report`        | Live Google Ads performance at any level                        |
| `get_poas_report`              | Profit on ad spend per product, campaign or account, with stock |
| `get_google_ads_changes`       | Who changed what in the account, last 30 days                   |
| `list_products_to_investigate` | Products that need attention first                              |
| `propose_change`               | File a proposal that a person approves in **Priorities**        |
| `search` / `execute`           | The whole Product Metrics API in Code Mode                      |

All 24 analysis tools and their arguments: [MCP tools](/docs/mcp/tools).

## What you can ask

```text
> Where is my Product Metrics setup, and what is the next step?
→ execute (GET /setup/status), or productmetrics setup get-status --json

> Connect my Shopify store to Product Metrics.
→ execute (POST /companies/:companyId/stores), or productmetrics stores connect
  --company-id <company_id> --provider shopify --json
  then gives you the link to approve the install in Shopify Admin

> Create the Product Metrics conversion actions in Google Ads.
→ execute (POST /properties/:propertyId/google-ads/conversion-actions),
  or productmetrics google-ads create-conversion-actions --property-id <property_id>
    --company-id <company_id> --json

> Which products lose money after ads this month?
→ list_properties, then get_poas_report (level: product,
  only_unprofitable: true)

> Did anyone change a budget or target ROAS before last week's drop?
→ list_properties, then get_google_ads_changes, or
  explain_google_ads_change
```

## Configuration

### Pin one store

To make the analysis tools read one store without asking, add the property to the URL. `search` and `execute` still work on your whole account.

```toml title="~/.codex/config.toml"
[mcp_servers.product-metrics]
url = "https://www.productmetrics.io/mcp?selectedAccountPropertyId=<propertyId>"
```

### Environment variables (productmetrics)

```bash
# never prompt, never open a browser, no colours
PM_AGENT=1
# an access token, for CI instead of productmetrics login
PM_TOKEN=...
# another API origin (default https://prod-backend.productmetrics.io)
PM_API_URL=...
```

The CLI stores its sign-in in `${XDG_CONFIG_HOME:-~/.config}/product-metrics/credentials.json`.

## Troubleshooting

| Problem                                                                           | Fix                                                                                                                             |
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Codex says the server needs sign-in                                               | Run `codex mcp login product-metrics` and finish the sign-in in the browser.                                                    |
| "This connection expired or was removed; connect Product Metrics again."          | Run `codex mcp login product-metrics` again. If that fails, remove the server and add it again.                                 |
| "This connection only has MCP access, so it cannot call the Product Metrics API." | Remove the server, add it again and allow everything the consent page shows.                                                    |
| "The MCP server is not enabled for this account yet."                             | Ask Product Metrics support to turn it on for your account.                                                                     |
| "This property needs a Product Metrics Pro subscription for the MCP server."      | Upgrade that store to Pro, or ask about another store.                                                                          |
| `productmetrics` can't reach the API from Codex                                   | Codex's sandbox may block network access for commands. Allow it for this session, or run `productmetrics` outside the sandbox.  |
| `productmetrics` exits `3`                                                        | Not signed in or missing a scope. Run `productmetrics login` in your own terminal; the hint names the scopes.                   |
| `productmetrics` exits `4`                                                        | A person must finish a step in a browser. Open `next_action.url`, then ask Codex to check the status again.                     |
| Codex doesn't use a skill                                                         | Run `npx skills list` and check it is installed for `codex`, then restart Codex.                                                |

## Where next

* [Setup and usage](/docs/mcp/connect): how sign-in works, every client
* [MCP tools](/docs/mcp/tools): every tool and argument
* [Skills](/docs/agent-skills/overview): what each skill does
* [CLI for agents](/docs/cli/for-agents): `--json`, exit codes and safe retries
* [Claude Code](/docs/integrations/claude-code) · [Cursor](/docs/integrations/cursor)
