Product Metrics in Codex
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 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.
productmetricsCLI: Codex runs it with JSON output.
You sign in in your browser. There is no API key.
Install
1. Add the MCP server
codex mcp add product-metrics \
--url https://www.productmetrics.io/mcpOr add it to ~/.codex/config.toml by hand:
[mcp_servers.product-metrics]
url = "https://www.productmetrics.io/mcp"2. Install the skills
From the project where you run Codex:
npx skills add https://www.productmetrics.io/docs \
--skill '*' \
--agent codex \
-yThis 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.
3. Install the productmetrics CLI (optional)
Install it from npm (Node.js 22 or later), then check it:
npm install -g @productmetrics/cli
productmetrics --versionTo 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:
codex mcp login product-metricsYour browser opens the Product Metrics consent page: sign in (or choose Continue with Google to create an account), check what Codex Can read and Can change, and click Connect Codex.
productmetrics CLI. Run this in your own terminal, not through Codex:
# opens the browser and waits up to 5 minutes
productmetrics login
# which API, signed in or not, scopes, expiry
productmetrics statusSo that productmetrics never prompts or opens a browser when Codex runs it, set PM_AGENT=1:
echo 'export PM_AGENT=1' >> ~/.zshrc
source ~/.zshrcecho 'export PM_AGENT=1' >> ~/.bashrc
source ~/.bashrc[System.Environment]::SetEnvironmentVariable("PM_AGENT", "1", "User")Restart your terminal after running this.
How it works
- Analysis tools read live.
list_propertiespicks the store, then tools such asexplain_google_ads_change,get_google_ads_reportandget_poas_reportread your Google Ads account and your store’s margins and stock. They never change Google Ads or your store. - Setup runs through Code Mode.
searchfinds an API operation;executeruns 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,
productmetricsexits4and puts the URL innext_action.url. - Skills load on demand. Codex reads a skill when your request matches its description.
- The CLI speaks JSON. Codex runs
productmetrics help agentsfirst, then passes--jsonto 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.
productmetricshides 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.
What you can ask
> 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_changeConfiguration
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.
[mcp_servers.product-metrics]
url = "https://www.productmetrics.io/mcp?selectedAccountPropertyId=<propertyId>"Environment variables (productmetrics)
# 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: how sign-in works, every client
- MCP tools: every tool and argument
- Skills: what each skill does
- CLI for agents:
--json, exit codes and safe retries - Claude Code · Cursor