MCP Integration

Connect UserTold.ai to Claude, Cursor, or any MCP-compatible agent for direct tool calls, resource reads, and prompts.

Connect

Add to your MCP client config:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "usertold": { "type": "http", "url": "https://mcp.usertold.ai/mcp" }
  }
}

Claude Code (.mcp.json in project root or ~/.claude/mcp.json):

{
  "mcpServers": {
    "usertold": { "type": "http", "url": "https://mcp.usertold.ai/mcp" }
  }
}

After adding the config, the client opens a browser login (OAuth 2.1 + PKCE). No manual token handling.

Remote MCP clients can discover OAuth metadata at /.well-known/openid-configuration and /.well-known/oauth-protected-resource. Dynamic client registration is supported at POST /api/oauth/register; pre-registered integrations can still use static clients.

Once connected, call initialize then tools/list to see active tool schemas. Deferred tool schemas are available through MCP resources.

Discover your workspace handle

Before projects.create, discover the authenticated user's default personal workspace handle in one of two supported ways:

Read result.user.personal_org_handle from the initialize response.
Call resources/read for usertold://me and read personal_org_handle.

Agents should use that handle when they need an orgHandle before a project exists.

projectRef

Most tools are scoped to a project. Accepted formats:

orgHandle/projectHandle — e.g. acme/billing
Project ID — e.g. proj_abc123

Tool catalog

Active tool schemas are discoverable through tools/list. Less common tools may be deferred to keep the active catalog focused; read usertold://mcp/deferred-tools for those names and then read the listed schema URI before calling the tool. The list below mirrors what's wired in src/backend/mcp/tools/index.ts at the time of writing.

projects

Tool	What it does
`projects.create`	Create a new project within an organization.
`projects.update`	Update project metadata. Requires owner or admin role.
`projects.delete`	Delete a project. Owner only.
`projects.get_context`	Deferred: planning snapshot with evidence counts, work item status, active studies, recent interviews, and coverage gaps.
`projects.get_config`	Deferred: get masked project settings (BYOK keys). Shows which keys are configured.
`projects.set_config`	Deferred: set a project configuration key. Allowed keys: `openai_api_key`. Owner or admin role required.

studies

Tool	What it does
`studies.create`	Create a study from a validated script.
`studies.get`	Get study details including script, goals, and status.
`studies.update`	Update metadata, script, goals, or status (including activation).
`studies.delete`	Delete a study.
`studies.validate_script`	Validate a study script and return a structural summary.

interviews

Tool	What it does
`interviews.list`	List interviews with filters (study, status, processing status) and pagination.
`interviews.upload_video`	Deferred: upload base64 audio bytes, with optional playback video bytes, as a custom async interview and queue the normal processing pipeline. Read `usertold://mcp/tools/interviews.upload_video` for the schema.
`interviews.get_context`	Deferred: get interview transcript messages within a time window around a given timestamp.
`interviews.processing_status`	Deferred: real-time processing status (transcription, evidence extraction) for an interview.

evidence

Tool	What it does
`evidence.list`	List evidence with filters. Defaults to the `product_under_test` target surface; pass `target_surface="all"` to include every surface.
`evidence.get`	Get full evidence detail including annotation and dismissal state.
`evidence.search`	Deferred: semantic + keyword search across evidence. Ranked matches.
`evidence.annotate`	Add or update an annotation on an evidence card.
`evidence.dismiss`	Dismiss or restore an evidence card — set `dismissed=true` with a reason to dismiss; `dismissed=false` to restore.
`evidence.link`	Link an evidence card to a work item, or unlink it by passing `taskId=null`. Evidence is recalculated on affected work items.

work

Tool	What it does
`work.list`	List work items with filters. Defaults to `product_under_test` surface and hides closed work items; pass `include_closed=true` to include `done`/`wont_fix`. Pass `enriched=true` to include `signal_types[]` and `linked_study_ids[]` per work item.
`work.search`	Deferred: semantic + keyword search across work items.
`work.get_evidence`	Deferred: full evidence package for a work item with linked evidence, quotes, context, and interview metadata.
`work.create_from_evidence`	Create an evidence review packet/work item from one or more evidence cards and calculate priority context. The created item still needs project-aware review before delivery handoff.
`work.update`	Update work item status and/or fields (kanban moves, edits).
`work.merge`	Deferred: merge a source work item into a target when two work items describe the same problem.
`work.delete`	Delete a work item.
`work.push`	Push a work item to a configured provider (GitHub Issues or Linear) with source quotes attached. Use it after project-aware verification; the tool does not determine verification itself.

intake

Tool	What it does
`intake.create`	Create a new intake with optional inline questions.
`intake.update`	Update intake fields or status (includes activation validation).
`intake.set_questions`	Replace all questions on an intake — deletes existing questions and inserts the new list in order.
`intake.delete`	Delete an intake.

Resource catalog

Resources are discoverable through resources/list and resources/templates/list. Stable URIs:

Global

usertold://me — current user profile + personal_org_handle
usertold://projects — every project the authenticated user can see
usertold://mcp/deferred-tools — deferred tool names with schema URIs for on-demand loading
usertold://mcp/tools/{name} — full schema for a deferred tool
usertold://docs/study-design-guide — study design guide for agents (also available via usertold study guide)

The OpenAPI document is published over REST at GET /api/openapi; fetch it from there instead of through MCP.

Project-scoped ({ref} is orgHandle/projectHandle or proj_...)

project://{ref}/overview — project-level evidence/work item counts and readiness
project://{ref}/evidence/recent — recent evidence
project://{ref}/evidence/{signalId} — single evidence card with full context
project://{ref}/interviews/recent — recent interviews
project://{ref}/interviews/{sessionId} — interview detail (transcript, events, media URLs)
project://{ref}/interviews/{sessionId}/transcript — extracted transcript text
project://{ref}/interviews/{sessionId}/events — interview event timeline
project://{ref}/studies — list studies
project://{ref}/studies/{studyRef}/script — study script
project://{ref}/studies/{studyRef}/interviews — interviews under that study
project://{ref}/work — list work items
project://{ref}/work/{taskId} — work item detail with linked evidence
project://{ref}/intake — list intakes
project://{ref}/intake/{screenerRef} — intake detail
project://{ref}/intake/{screenerRef}/responses — intake response summary

Prompt catalog

Available via prompts/list and prompts/get:

research.draft_study_script — draft a study script for a given objective and block flow
research.draft_recruitment_story — draft a recruitment story / intake description for a study
research.improve_script_iterations — suggest script improvements based on interview results
research.design_roadmap — propose a research roadmap from the current project state
research.interpret_study_snapshot — interpret the current state of a study

Research loop

A typical agent workflow:

Call projects.get_context to understand current evidence counts, work item status, and coverage gaps
Design and activate a study (studies.validate_script → studies.create → studies.update to activate)
Interviews run automatically as users interact with the widget
List and curate extracted evidence (evidence.list / evidence.search / evidence.annotate / evidence.dismiss / evidence.link)
Create evidence review packets from evidence clusters (work.create_from_evidence)
Review source evidence (work.get_evidence), merge duplicates (work.merge), and decide which packets are delivery-ready
Use work.push for work items you have verified and decided are delivery-ready
Complete linked Linear issues so current evidence resolves and future interviews can be watched for possible recurrence