Give your agent a direct line to real users.

UserTold gives product and coding agents tools to design studies, make them available in-product, and receive source-linked evidence after real users take part. MCP and CLI operations return machine-readable JSON so agents can inspect the source before deciding what should become work.

# MCP research sequence
read usertold://projects
studies.create
studies.update → status active
→ participants start interviews in the widget
interviews.list
evidence.list
work.create_from_evidence
verify Work → status ready
work.push
Linear completion resolves current evidence
Get startedRead the docs

The loop

From an agent-run interview to source-linked evidence

1

usertold://projects

Choose an accessible project from the bounded MCP bootstrap resource before making project-scoped calls.

2

studies.create

Create a structured study from a validated script — goals, segments, and conductor modes in one call.

3

Interviews run

The widget embeds in your product. Interviews capture real usage, silent observation, planned debriefs, and recordings.

4

evidence.list

After interviews complete, list extracted evidence: struggling_moments, desired_outcomes, workarounds.

5

work.create_from_evidence

Group related evidence into draft Work in the backlog, with interview quotes and source moments attached.

6

Work review

Verify the evidence, grouping, and current project context before moving Work from backlog to ready.

7

work.push

Push only ready Work to GitHub Issues or Linear with source quotes and evidence context attached.

8

Linear completion sync

When a linked Linear issue is completed, resolve the current work item evidence and keep watching new interviews for similar evidence that may resurface.

Connect

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.*
evidence.*
work.*
interviews.*

Connect

Start from CLI

For write-capable headless setup, export a user-delegated bearer from the CLI OAuth flow. Protocol-native usk_... auth.md keys are read-only after email OTP claim.

usertold auth login
export USERTOLD_API_KEY="$(usertold auth token)"
usertold init --name "My Product" --format json --yes
usertold project use <projectRef>
usertold study create --title "My Product Study" --activate --format json
usertold interview list --format json
usertold evidence list --format json

What comes back

Output contract

CLI commands can emit structured output with --json or --format json. MCP tools publish input and output schemas during discovery and return bounded structured results.

{
  "signalId": "sig_abc123",
  "signal_type": "struggling_moment",
  "quote": "I tried this flow three times and still cannot find where to change billing.",
  "confidence": 0.91,
  "intensity": 0.8,
  "interviewRef": "ses_xyz789",
  "timestamp_ms": 142300,
  "page_url": "/checkout/step-3"
}

Connect your agent to real user feedback

Give it access to study setup, in-product interviews, source-linked evidence, and reviewed tracker handoff.

Get startedIntegration docs