Create a user story under a feature

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

What it does

Creates a user story: one specific thing a user needs from a feature, written in three parts. Example for a "Checkout" feature: asA "returning shopper", iWant "to pay with a saved card", soThat "I can check out in one click". It is stored as a test suite with type=user-story under its parent feature, so the tests that prove the story works can be attached to it. Find or create the parent first (feature.list, feature.create) and pass its id as parentFeatureId. Titles must be unique across all suites in the workspace. A new story starts in lifecycle stage "authoring". Returns the saved suite plus suiteId (also as id), uri and nextSteps. Next: call case.create_batch with that suiteId to add its acceptance criteria as test cases (an acceptance criterion is one testable promise, like "a saved card is charged without re-entering the number").

Ask your agent

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

  • “Write a user story for paying with a saved card”
  • “Break the checkout feature into user stories”
  • “As a shopper I want to track my order, add that as a story”

Inputs

NameTypeDescription
title
required
stringShort story name, unique in the workspace. Example: "Pay with a saved card".
description
optional
stringExtra detail or context for the story. Defaults to empty.
parentFeatureId
required
stringId of the feature (or sub-feature) this story belongs to: the id or suiteId from feature.list or feature.create.
asA
required
stringWho the user is (the "As a ..." part). Example: "returning shopper".
iWant
required
stringWhat they want to do (the "I want ..." part). Example: "to pay with a saved card".
soThat
required
stringWhy it matters to them (the "so that ..." part). Example: "I can check out in one click".
storyPoints
optional
integerRough size of the work, a whole number from 1 (tiny) to 13 (large). Teams often use 1, 2, 3, 5, 8, 13. Optional.
assigneeId
optional
stringUser id of the person building the story. Your own id is user.id from project.whoami.
priority
optional
enumHow important it is. P0 = critical, must ship; P1 = high; P2 = normal (default); P3 = nice to have.
Allowed: P0P1P2P3

The MCP call

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "userstory.create",
    "arguments": {
      "title": "<title>",
      "parentFeatureId": "<parentFeatureId>",
      "asA": "<asA>",
      "iWant": "<iWant>",
      "soThat": "2026-01-01T00:00:00Z"
    }
  }
}

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.