MCP + CLI

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.

# Tool call sequence
projects.get_context
studies.create
studies.update → status active
→ participants start interviews in the widget
evidence.list
work.create_from_evidence
verify packet context
work.push
Linear completion resolves current evidence
Get startedRead the docs

From an agent-run interview to source-linked evidence

1

projects.get_context

Assess evidence distribution, work item status, active studies, and coverage gaps for the current project.

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

Create evidence review packets from evidence clusters. Each packet links back to interview quotes for verification.

6

Packet verification

Review the packet against source evidence and project context before deciding whether it becomes delivery work.

7

work.push

Push verified work items 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.

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.*
projects.*
intake.*

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

Output contract

Every command outputs --json. Every MCP resource is structured JSON, with a documented schema published at /api/openapi.

{
  "id": "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,
  "session_id": "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.

Integration docsGet started