Recipes

Concrete patterns you can copy and adapt. Each one assumes userintuition-mcp is on your PATH and you have either run userintuition-mcp login or set USERINTUITION_API_KEY.

Cost gate in CI

Refuse to merge a PR if its planned panel recruit would exceed a budget. estimate_panel returns the current cost and heuristic timeline without launching or charging anything:

#!/usr/bin/env bash
set -euo pipefail

estimate=$(userintuition-mcp estimate_panel \
  --study_id "$STUDY_ID" \
  --target 25 \
  --incident_rate 50 \
  --country_code US)

cost_usd=$(jq -r '.estimated_total_cost_usd' <<<"$estimate")

budget_usd=750

if (( $(echo "$cost_usd > $budget_usd" | bc -l) )); then
  echo "::error::Panel would cost \$$cost_usd — exceeds \$$budget_usd cap" >&2
  exit 1
fi

echo "Panel estimate: \$$cost_usd ✓"

Inspect fielding and retrieve a report

After a person launches recruitment through an MCP client, inspect its progress and retrieve a generated report. This script observes fielding for up to 24 hours, then queues and polls report generation:

#!/usr/bin/env bash
set -euo pipefail

study_id="$1"
target=25

# Recruitment is approved and launched through an MCP client.

# 2. Poll — list_interviews returns a total_count envelope, so page_size 1 is
#    enough. Filter to completed interviews: the unfiltered total also counts
#    in-progress and failed sessions.
deadline=$(( $(date +%s) + 86400 ))
while (( $(date +%s) < deadline )); do
  n=$(userintuition-mcp list_interviews \
      --study_id "$study_id" --status completed --page_size 1 \
      | jq -r '.total_count // 0')
  echo "  completed=$n/$target"
  (( n >= target )) && break
  sleep 600
done

# 3. Analyze and export
job_id=$(userintuition-mcp generate_report --study_id "$study_id" | jq -er '.job_id')
report_deadline=$(( $(date +%s) + 1800 ))
while true; do
  job=$(userintuition-mcp get_report_job --study_id "$study_id" --job_id "$job_id")
  status=$(jq -r '.status' <<<"$job")
  case "$status" in
    succeeded) break ;;
    failed|cancelled) echo "$job" >&2; exit 1 ;;
  esac
  (( $(date +%s) < report_deadline )) || { echo "Report job still pending: $job_id" >&2; exit 1; }
  sleep 5
done
userintuition-mcp get_study_report --study_id "$study_id" \
  > "report-$study_id.json"
echo "Saved: report-$study_id.json"

Daily standup digest

A cron job that writes per-study interview counts into a Slack-ready text file every morning. list_interviews with page_size: 1 is the cheap way to count — the envelope’s total_count covers the whole study, not just the page:

#!/usr/bin/env bash
set -euo pipefail

userintuition-mcp list_studies --page_size 50 \
  | jq -r '.studies[] | "\(.id)\t\(.name)"' \
  | while IFS=$'\t' read -r id name; do
      n=$(userintuition-mcp list_interviews \
          --study_id "$id" --status completed --page_size 1 \
          | jq -r '.total_count // 0')
      echo "  • $name — $n completed interviews"
    done > /tmp/studies-digest.txt

# Then post via your Slack tool of choice
cat /tmp/studies-digest.txt

Schedule with cron:

0 9 * * 1-5 USERINTUITION_API_KEY=ui_sk_... /usr/local/bin/digest.sh

Bulk cleanup of test studies

Delete every study whose name starts with test_:

userintuition-mcp list_studies --page_size 100 \
  | jq -r '.studies[] | select(.name | startswith("test_")) | .id' \
  | while read -r id; do
      echo "Deleting $id"
      userintuition-mcp delete_study --study_id "$id"
    done

delete_study is destructive. Sanity-check the jq filter against list_studies output before running the loop.

Review low-quality interviews

List interviews classified as Poor, then fetch each full record for review:

#!/usr/bin/env bash
set -euo pipefail

study_id="$1"

userintuition-mcp list_interviews \
  --study_id "$study_id" --quality '["Poor"]' --page_size 100 \
  | jq -r '.interviews[].id' \
  | while read -r id; do
      userintuition-mcp get_interview --interview_id "$id" > "interview-$id.json"
      echo "Saved interview-$id.json"
    done

delete_interview --interview_id <id> is available after review, but deletion is destructive. The public API does not expose a reversible hide operation.

Discovering tools by capability

The CLI exposes 75 direct tool commands. Use its local inventory to discover commands. To find one for a job:

# Anything that creates something
userintuition-mcp list | grep ^create_

# Anything related to interviews
userintuition-mcp list | grep interview

# Inspect a candidate
userintuition-mcp describe create_participants

This is often faster than scrolling the tool reference.

Patterns to avoid

Don’t hard-code IDs. Always derive them from a fresh list_* call. IDs from a teammate’s account won’t resolve.
Use MCP for paid panel launch. The person reviews the saved plan and quote and approves through the App or explicit chat confirmation.
Don’t count by page. Read list_interviews.total_count instead of counting one page’s interviews array.
Don’t parse stdout in shell with grep/sed. Use jq — responses are JSON and may add fields between versions.
Don’t share your USERINTUITION_API_KEY in CI logs. Mask it as a secret. Anyone with the key can spend panel budget on your account.

Get Started

Reference

Guides

Cost gate in CI

Inspect fielding and retrieve a report

Daily standup digest

Bulk cleanup of test studies

Review low-quality interviews

Discovering tools by capability

Patterns to avoid

​Cost gate in CI

​Inspect fielding and retrieve a report

​Daily standup digest

​Bulk cleanup of test studies

​Review low-quality interviews

​Discovering tools by capability

​Patterns to avoid

Cost gate in CI

Inspect fielding and retrieve a report

Daily standup digest

Bulk cleanup of test studies

Review low-quality interviews

Discovering tools by capability

Patterns to avoid