MCP Integration

UserTold captures consented in-product interviews: voice and transcripts, in-page behavior and page context, plus screen sharing a participant approves in a supported desktop browser.

Interviews produce source-linked Evidence from what participants said, did, and saw; related Evidence becomes draft Findings for review. Generated transcripts and analysis do not replace the captured source.

UserTold does not recruit participants or replace consent. Mobile and unsupported browsers continue without screen sharing. Denied permissions, interruptions, and failures can leave capture gaps.

Fast path: let your agent work with existing research

Using ChatGPT or Codex? Install the UserTold plugin.

For other MCP clients, connect directly:

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

Call projects.list to find my existing Projects. If I need a new Project, call organizations.list to get its organizationRef. Ask me to select or create a Project, then proceed. Propose changes before acting.

Clients use OAuth 2.1 with PKCE; no API token is needed.

For new research goals, call setup.recommend for documentation guidance. It does not inspect or change the workspace. For references, call projects.list or organizations.list directly, without MCP resources. Each returns up to 25 records; when truncated, increase offset by count.

Pass projectRef to studies.list to inspect the starter Study. For a new Project, pass organizationRef to projects.create. MCP resources remain available to supporting clients.

Agents can download authorized Interview artifacts through short-lived links, inspect Evidence, maintain Findings, and send them to delivery. Private admin stays in the dashboard.

Set up from the console

Use the Project home's agent prompt for installation. Read projects.get_widget_setup for the verified page, active Study, and remaining blockers.

Operate safely

• Propose Study changes before acting. Activating a Study starts participant capture; closing stops new interviews but not one in progress.
• Review completed research with studies.get_results; follow its references with evidence.get and interviews.get_context, or interviews.get_artifacts for short-lived links to TXT, VTT, audio, screen, and source events (JSONL). Download transcript_text once for the exact transcript.
• Before changing or sending a Finding, read its Evidence with findings.get_evidence and the Interview with interviews.get_context.
• Read interviews.processing_status before interviews.retry_processing; never retry on a loop.
• Sending is explicit, separate from updating a Finding, and uses the Project-configured GitHub or Linear destination unless you pass a provider.
• Report problems through feedback.submit only with approval. Exclude credentials, participant identity, and private research content.

If setup fails

Reconnect for authorization errors. If advice fails, continue with projects.list, studies.list, and setup tools. For capture failures, run projects.verify_widget_installation: it checks page HTML, not widget execution; runtime failures emit usertold:integration-error (Widget Integration).

For 401, follow WWW-Authenticate → resource_metadata → authorization_servers and complete OAuth with PKCE. A scanner stopping at 401 has not verified protected resources.

Self-discovery and next steps

Use authenticated tools/list and resources/list; their responses own the current inventory.

• Server Card
• Quickstart
• Widget integration

External website recordings

recordings.create_website_invitation prepares a project from a URL. recordings.create_invitation uses an existing project. Both return guest launch instructions. Participants need no account. Use recordings.get_results for status and recordings.update_invitation to share or revoke access.