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

# Setup and usage (/docs/mcp/connect)

<!-- agent-signals: reading_time_min: 5 · est_tokens: 2055 · updated: 2026-11-16 -->
Related: [Product Metrics MCP server](/docs/mcp/overview.md), [Product Metrics MCP tools](/docs/mcp/tools.md), [Rules of Product Metrics](/docs/concepts/rules.md)

> Connect Product Metrics to an MCP client with OAuth, choose a property, and check the connection works.

## Server URL

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

Add this URL to your MCP client as a remote server. Product Metrics uses OAuth: your client opens the Product Metrics consent page, where you sign in and click **Connect** with the app's name (for example **Connect Claude**). No API key or custom header is needed.



**Manual JSON configuration**

Clients that use JSON configuration accept this shape:

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



> **Note:** `productmetrics mcp-config` prints `https://prod-backend.productmetrics.io/mcp`, the same server on the API's own origin. Either URL works, and a token from one works on the other.

## Before you start

* **A Product Metrics account.** No account yet? The consent page offers **Continue with Google** and creates one. The assistant can then set up your workspace with the API tools.
* **Pro on each property** you want the analysis tools to read. Without it the assistant gets "This property needs a Product Metrics Pro subscription for the MCP server."
* **The MCP server turned on for your account** for the analysis tools. If the assistant says "The MCP server is not enabled for this account yet", ask Product Metrics support to turn it on.

## Choose a property

The analysis tools read one property (one store with its Google Ads account). You can choose it in two ways:

* **Name the store in your question.** The assistant calls `list_properties` and passes that store's `property_id`. With one property, it uses that one without asking.
* **Pin one property in the URL**, for a script or agent that should only see one store:

  ```text
  https://www.productmetrics.io/mcp?selectedAccountPropertyId=<propertyId>
  ```

The API tools (`search`, `execute`) ignore the pin: they work on your whole account, with the ids in each operation's path. See [How workspaces and properties work](/docs/mcp/overview#how-workspaces-and-properties-work).

## Client-specific setup

### Claude and Claude Desktop

Open [**Add custom connector**](https://claude.ai/new?modal=add-custom-connector#customize/connectors) (or **Settings → Connectors → Add custom connector**), name it `Product Metrics` and enter the server URL. See [Claude](/docs/integrations/claude).

### ChatGPT

Turn on developer mode, create an app with the server URL and **OAuth**, then sign in. See [ChatGPT](/docs/integrations/chatgpt).

### Claude Code

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

Then run `/mcp` in Claude Code to sign in. See [Claude Code](/docs/integrations/claude-code).

### Cursor

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

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

See [Cursor](/docs/integrations/cursor).

### Other MCP clients

Add `https://www.productmetrics.io/mcp` as a remote HTTP MCP server and complete the OAuth flow your client opens. Menu names and configuration files vary between clients. For Codex, see [Codex](/docs/integrations/codex).



> **Tip:** **From the CLI**, `productmetrics mcp-config --client claude` (or `chatgpt`, `cursor`) prints the URL and these steps for one client. Without `--client` it prints all of them.

## How sign-in works

The server uses OAuth 2.1, so any MCP client that supports it connects with the URL alone.

1. The client calls `https://www.productmetrics.io/mcp` and gets `401` with a pointer to the protected-resource metadata:

   ```text
   https://www.productmetrics.io/.well-known/oauth-protected-resource/mcp
   ```

2. That document names the Product Metrics authorization server (`https://prod-backend.productmetrics.io`) and its scopes: `mcp`, `read`, `setup` and `write`.

3. The client registers itself (dynamic client registration or a Client ID Metadata Document) and sends you to the Product Metrics consent page with PKCE.

4. You check what the page says the app **Can read** and **Can change**, and click **Connect** with the app's name (for example **Connect Claude**). The client swaps the code for a Product Metrics token.

The consent page shows the request before you sign in. Signed out, its button is **Continue with Google**: it signs you in, or creates an account, and brings you back to the same page to connect. **Already have an account? Sign in** under the card uses your usual sign-in. A request expires after 30 minutes: start connecting again from your client.

The token works only for the MCP server and the [public API](/docs/api/overview): it is not a Product Metrics session and cannot open the app.

* **Access tokens** last one hour and are renewed automatically.
* **30 days** after you connect, the connection ends and you sign in again, however often you use it.
* Your access is checked on every request.

## Verify the connection

Start with any of these:

* "Which Product Metrics stores can I open?" → `list_properties`
* "Where is my Product Metrics setup, and what is the next step?" → `execute` with `GET /setup/status`
* "Why did my Google Ads ROAS drop last week?" → `explain_google_ads_change`
* "Which products should I look at first?" → `list_products_to_investigate`

The [overview](/docs/mcp/overview) documents every tool. [MCP tools](/docs/mcp/tools) lists every argument.

## Disconnect

Remove the connector in the assistant's settings. To revoke the app's access on the Product Metrics side as well, ask Product Metrics support: a revoke deletes the app's tokens and takes effect within about a minute.

## Troubleshooting

| What the assistant says                                                           | What to do                                                                                                                                                   |
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| "This connection expired or was removed; connect Product Metrics again."          | Reconnect: remove the connector and add it again, or sign in again from the client's MCP settings.                                                           |
| "This connection only has MCP access, so it cannot call the Product Metrics API." | Remove Product Metrics from the client and add it again: the client asks for MCP access only. Allow the read, setup and write access the consent page shows. |
| "The MCP server is not enabled for this account yet."                             | Ask Product Metrics support to turn on the MCP server 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.                                                                                                       |
| "No property chosen."                                                             | Tell the assistant which store you mean; it calls `list_properties` and tries again.                                                                         |
| "The limit of … tool calls per hour … is reached."                                | Wait the minutes it names. Expensive tools have a lower hourly limit: see [MCP tools](/docs/mcp/tools).                                                           |

## For AI assistants

If you are an AI assistant and the Product Metrics tools (list_properties, search, execute and the rest) are not available to you, the user has not connected the MCP server yet. Give them the URL [https://www.productmetrics.io/mcp](https://www.productmetrics.io/mcp) and the steps for their client from this page. Never ask the user for a password, token or API key: sign-in happens in their browser on a Product Metrics page. For what each tool does, read [https://www.productmetrics.io/docs/mcp/overview](https://www.productmetrics.io/docs/mcp/overview).
