Give your agent a direct line to real users.

Your agent prepares a study and reviews the results after users take part. Interviews, evidence, and Findings are available as structured data. Review the sources before sending a Finding to Linear or GitHub.

Connect your agent MCP integration guide

MCP · CLI · REST · ChatGPT pluginOAuth 2.1, no token to pasteJSON, schema per tool

Illustrative agent session · claude codeproject acme/app · study onboarding-friction

00:00readusertold://projects2 projects accessible · acme/app selected
00:04callstudies.createonboarding-friction · draft · observe ordinary use, then a planned debrief
00:09callstudies.updatestatus active · the installed widget starts inviting trial users
6 days
Fourteen real users take part inside the product. The agent is not in the room.
+6dcallinterviews.list14 completed · 1 processing
+6dcallevidence.list9 struggling moments · 3 about billing · confidence ≥ 0.86
+6dcallevidence.getI expected billing under account settings. I went back twice and still couldn’t find it./settings/account · 02:22 · confidence 0.91
+6dcallfindings.create_from_evidencedraft · Users look for billing in account settings · 3 sources
Review
A human or a project-aware agent opens the three sources and marks the Finding reviewed.
+7dcallfindings.sendLinear UT-214 · quotes and source moments attached
+19deventUT-214 completedevidence resolved · new interviews watched for the same stall

1 read · 7 calls · 1 event · 2 waitsWhat the user sees at each stage →

Connect

Connect over MCP, the plugin, the CLI, or REST

All four access the same projects, studies, interviews, evidence, and findings. MCP can also provide authorized download links for available interview recordings and source artifacts.

MCP

Claude Code · Cursor · Codex · any MCP client

https://mcp.usertold.ai/mcp

OAuth 2.1 with PKCE in the browser; no token to paste. Each tool ships its input and output JSON Schema in the tools/list response.

projects · studies · interviews · evidence · findings

UserTold plugin

ChatGPT · Codex

The same tools inside ChatGPT and Codex, without configuring an MCP client.

Open UserTold plugin

CLI

Shell · CI · headless agents

npm install -g usertold

--json on every command. --help --json describes the whole surface without parsing prose.

REST

Direct integrations

usertold.ai/api/openapi

The same project-scoped endpoints with an OpenAPI schema. Authenticate with the bearer the CLI mints.

First session

Connect with one prompt, or from the shell

Over MCP the agent connects itself: paste one prompt and finish the browser authorization. From a shell, sign in once and every later command runs headless with structured output.

Paste into any MCP client

Help me connect UserTold to this agent with https://mcp.usertold.ai/mcp and complete browser authorization.

Discover the organization and Project bootstrap resources. Ask me to select or create a Project, then proceed. Propose changes before acting.

Browser authorization: OAuth 2.1 with PKCE. You never paste a token.
Bootstrap resources: It reads usertold://organizations and usertold://projects, then asks you to pick or create a project.
Proposals before actions: Every change is proposed before it runs, including activating a study.

Or from the shell

# sign in once, in a browser
usertold auth login
# a user-delegated bearer for headless runs
export USERTOLD_API_KEY="$(usertold auth token --json | jq -r .token)"
# a project, without prompts
usertold init --name "My Product" --format json --yes
usertold project use <projectRef>
# a study, activated in the same call
usertold study create --title "My Product Study" --activate --format json
# what came back
usertold interview list --format json
usertold evidence list --format json

An agent can request its own usk_… key through /auth.md and use it only after a person enters the emailed code; it then reads but does not write. For writes, sign in with usertold auth login and export the token as above.

What comes back

What one evidence item contains

What was said, what was observed, and what the model inferred are separate fields, with the interview, the moment, and the page when they are known. Your agent can check the source before it decides anything. Every tool ships its full schema in tools/list; the CLI mirrors it with --format json.

evidence.get · excerpt

{
  "signalId": "sig_abc123",
  "signal_type": "struggling_moment",
  "quote": "I tried this flow three times and still cannot find where to change billing.",
  "observed_facts": [
    "Returned to /checkout/step-3 three times",
    "Opened account settings between attempts"
  ],
  "interpretation": "Billing settings are not where users look for them during checkout.",
  "confidence": 0.91,
  "intensity": 0.8,
  "interviewRef": "ses_xyz789",
  "timestamp_ms": 142300,
  "page_url": "/checkout/step-3",
  "review_status": "published",
  "findingRefs": ["tsk_7f3a21"]
}

quote: The participant’s words, verbatim, when they said something. Behavior-only evidence leaves it empty.
observed_facts: What the recording shows, as short statements. The source when there is no quote.
interpretation: What the model inferred, in its own field, so it never blends with the quote or the facts.
signal_type: One of eleven generated types, from struggling_moment and desired_outcome to decision_point. Related items are grouped into draft Findings for you; findings.create_from_evidence lets an agent group them itself.
confidence · intensity: How sure the model is, and how strongly the participant meant it. evidence.list takes min_confidence; intensity comes back on the record for you to threshold yourself.
interviewRef · timestamp_ms: The moment inside the interview. interviews.get_context returns the transcript around it.
page_url: Where it happened, when the page is known. Null otherwise.

Constraints

Review and access controls

Review requirements, retry limits, account access, and recording downloads.

findings.send

→ Error: Finding must be reviewed before provider handoff.

Review the Finding and its sources before sending it. Record the review through findings.update, then choose a destination with findings.send.

interviews.retry_processing

→ Only durable failures or processing past the conservative 24-hour no-progress guard can be retried.

Check interviews.processing_status first. A retry replaces generated evidence, keeps manual evidence, and is refused while processing is still moving.

initialize

→ server info, no account identity

The handshake says what the server is, not who you are. Identity comes from the bounded usertold://organizations and usertold://projects resources after authorization.

interviews.get_artifacts

→ authorized download links with an expiry

Read transcripts and context with interviews.get_context. Use interviews.get_artifacts to download available recordings and source artifacts through short-lived links.

Connect your agent to real user feedback

Let your agent prepare a study and review the results. Keep the source links with any Finding it sends to your tracker.

Connect your agent Integration docs