Create a product KPI

productkpi.createChanges dataCreates, updates or deletes something in your workspace.

What it does

Defines a new product KPI (key performance indicator): one number that shows whether the whole product is succeeding. Example: name "Weekly active users", unit "users", direction higher-better, targetValue "5000". Use this for product-wide numbers and featuremetric.create for numbers about a single feature (like checkout conversion rate). Call project.whoami to confirm the workspace and productkpi.list first, since duplicate names are not blocked. This only defines the KPI; record actual values over time with metric.observe. New KPIs are always saved with status "active". Returns {success, data: the saved KPI including its id, uri}.

Ask your agent

You don’t call productkpi.create yourself. Say something like this to Claude Code, Cursor or another MCP-connected agent:

  • “Track weekly active users with a goal of 5,000”
  • “Add a KPI for monthly recurring revenue”
  • “We want churn under 3 percent, set that up as a KPI”

Inputs

NameTypeDescription
name
required
stringKPI name, up to 128 characters. Examples: "Weekly active users", "Monthly recurring revenue", "Churn rate".
description
optional
stringHow the KPI is defined, in plain words. Example: "Distinct users who signed in at least once in the last 7 days."
unit
required
stringWhat the numbers measure, free text up to 32 characters. Examples: "users", "percent", "usd", "seconds", "count".
direction
required
enumWhich way is good. higher-better = bigger numbers are good (active users, conversion rate); lower-better = smaller numbers are good (page load seconds, churn rate, error count).
Allowed: higher-betterlower-better
targetValue
optional
stringThe goal to reach. A plain number in a string: digits and an optional decimal point, no commas, symbols or units. It is stored as a number, so "5,000" or "5%" is rejected. Examples: "5000" users, "3" percent churn.
measurementMethod
optional
stringHow the number is collected, free text up to 32 characters. Default "manual" (someone records values with metric.observe). Other examples: "integration:posthog", "integration:amplitude", "sql". A label only; nothing is collected automatically.
measurementConfig
optional
objectOptional free-form JSON object describing where the data comes from; stored as-is, not acted on. Example: {"tool": "posthog", "event": "checkout_completed", "window": "7d"}.
ownerId
optional
stringUser id of the person accountable for the KPI. Your own id is user.id from project.whoami.
status
optional
enumCurrently ignored: new KPIs are always saved as "active". (archived = no longer tracked.)
Allowed: activearchived

The MCP call

What the agent’s MCP client sends (placeholders in angle brackets):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "productkpi.create",
    "arguments": {
      "name": "<name>",
      "unit": "<unit>",
      "direction": "higher-better"
    }
  }
}

Connect your agent

npx -y @testmaze/mcp init tmt_xxx
claude mcp add tm --scope project -- npx -y @testmaze/mcp

Create the token in your Test Maze workspace under Settings → MCP. Setup for Cursor, Cline, Gemini CLI and Codex CLI is shown there too.