MCP + CLI

Built for agents. Not just compatible.

UserTold.ai exposes a full MCP server and CLI with machine-readable JSON output at every layer. Your agent designs studies, triggers sessions, reads structured signals, and pushes evidence-backed tasks — all programmatically.

# Tool call sequence
projects.signal_health
studies.create
→ sessions run automatically
signals.list
tasks.create_from_signals
tasks.push
tasks.measure
Get startedRead the docs

The research loop

1

projects.signal_health

Assess signal distribution and planning readiness for the current project.

2

studies.create

Create a structured study from a script. Idempotent — safe to call repeatedly.

3

Sessions run

The widget embeds on your product. Real users are interviewed. Sessions record automatically.

4

signals.list

After sessions complete, list extracted signals: struggling_moments, desired_outcomes, workarounds.

5

tasks.create_from_signals

Generate evidence-backed tasks from signal clusters. Each task links back to session quotes.

6

tasks.push

Push tasks to GitHub Issues or Linear. Returns issue URLs.

7

tasks.measure

Re-interview on the same topic. Compare signal rates before and after deployment.

Start from MCP

Base URL

https://mcp.usertold.ai/mcp

Protocol

HTTPS JSON-RPC over POST

Auth

OAuth connect flow (Authorization Code + PKCE)

Tool domains

studies.*
signals.*
tasks.*
sessions.*
projects.*

Start from CLI

export USERTOLD_API_KEY=<your_key>
usertold init --name "My Product" --format json --yes
usertold study create <projectRef> --title "My Product Study" --type jtbd --activate --format json
usertold session list <projectRef> --format json
usertold signal list <projectRef> --format json

Output contract

Every command outputs --json. Every MCP resource is structured JSON. Schema is stable across releases.

{
  "id": "sig_abc123",
  "type": "struggling_moment",
  "quote": "I tried this flow three times and still cannot find where to change billing.",
  "confidence": 0.91,
  "session_id": "ses_xyz789",
  "timestamp_ms": 142300,
  "url": "/checkout/step-3"
}

Ready to build?

Connect your agent to the MCP server or set up the CLI and start your first study in minutes.

Integration docsGet started