Skip to main content

MCP

MCP (the Model Context Protocol) lets AI tools such as ChatGPT, Claude, Claude Code and Cursor use other services. User Evaluation's MCP server lets them read your studies, transcripts, study reports and reports, search what participants said and ask Eva. With write access they can also set up, launch and run studies, invite people, and make clips, reels and reports.

  • Server address: https://api.userevaluation.com/mcp
  • Transport: Streamable HTTP. There is nothing to install.
  • Sign-in: OAuth (you sign in to User Evaluation and approve the client), or an API key sent as Authorization: Bearer ue_live_….

Connect ChatGPT or Claude​

ChatGPT and Claude (on the web and in Claude Desktop) connect as a custom connector. You don't need an API key.

  1. ChatGPT: go to Settings → Apps & Connectors, turn on developer mode if asked, and choose Create. Claude: go to Settings → Connectors and choose Add custom connector.
  2. Name it User Evaluation and enter https://api.userevaluation.com/mcp as the URL. In ChatGPT, choose OAuth for authentication.
  3. A User Evaluation page opens. Sign in if you need to.
  4. Choose the workspace to connect (if you're in more than one) and what the assistant may do:
    • Read your research and ask Eva (always on).
    • Make changes: set up and run studies, invite people, and make clips and reports, as you can in the app. Steps that cost money or email people need your yes first. Observers can't give this.
  5. Choose Allow. You're sent back to ChatGPT or Claude, and the connector is ready.

The connection shows in Settings → API & MCP → Connected, with who connected it, what it may do and how many calls it made.

Connect Claude Code​

claude mcp add --transport http userevaluation https://api.userevaluation.com/mcp

Then run /mcp in Claude Code and choose userevaluation. Your browser opens the same sign-in and approval page.

Connect with an API key​

Cursor, VS Code and other clients that can send a header can use an API key instead.

  1. Go to Settings → API & MCP and create an API key. Tick Read only if the assistant only needs to read.
  2. Copy the key. It is shown only once.
  3. Add the server to your client. Put your key in place of ue_live_….

Cursor (~/.cursor/mcp.json)

{
"mcpServers": {
"userevaluation": {
"url": "https://api.userevaluation.com/mcp",
"headers": { "Authorization": "Bearer ue_live_…" }
}
}
}

VS Code (.vscode/mcp.json)

{
"servers": {
"userevaluation": {
"type": "http",
"url": "https://api.userevaluation.com/mcp",
"headers": { "Authorization": "Bearer ue_live_…" }
}
}
}

For client developers: OAuth details​

The server follows the MCP authorization spec:

  • A request without a valid token gets 401 with WWW-Authenticate: Bearer resource_metadata="https://api.userevaluation.com/.well-known/oauth-protected-resource/mcp".
  • Protected Resource Metadata (RFC 9728) is at /.well-known/oauth-protected-resource and /.well-known/oauth-protected-resource/mcp. Authorization Server Metadata (RFC 8414) is at /.well-known/oauth-authorization-server (also served at /.well-known/openid-configuration).
  • Clients register with Dynamic Client Registration (RFC 7591) at POST /register. Clients are public (token_endpoint_auth_method: none). Redirect URIs must be https, http on localhost/127.0.0.1, or an app's own scheme, and must match exactly at /authorize.
  • GET /authorize takes the authorization code flow with PKCE S256 (required) and the resource indicator (RFC 8707). The redirect back carries code, state and iss.
  • POST /token supports authorization_code and refresh_token. Access tokens last one hour. Refresh tokens last 30 days and work once: each refresh returns a new pair. Using an old refresh token again revokes the connection.
  • POST /revoke (RFC 7009) revokes the connection a token belongs to.
  • Scopes: read (read and ask Eva) and write (the write tools below; Eva may change things with approval in the app). Tokens only work on the MCP server, not on the REST API.

Tools​

ToolWhat it does
list_studiesLists studies, newest first. Filter by status or type, or search with q.
get_studyOne study: question, guide, screener, audience and status. Takes an id or a slug.
get_study_statusA study's status and progress: invited, booked, completed, quality, next session.
list_sessionsA study's sessions, without transcripts.
get_sessionOne session with its full transcript, chapters and signals.
get_readoutThe study report for a study: themes, claims with their clips, next steps.
list_reports / get_reportReports in the workspace, and one report with its document.
list_swarm_runsSwarm runs, newest first.
list_findings / get_findingThe findings of a Swarm run, and one finding with its evidence.
searchFinds studies, reports, chats, Library files, projects, Swarm runs and people by name.
search_evidenceSearches what participants said: transcripts, clips, Library transcripts and study report claims.
list_library_files / get_library_fileLibrary files, and one file with its transcript.
ask_evaAsks Eva. The answer cites its evidence and is saved as a chat in the app.
create_draft_studyDrafts a study from a research question. Nothing is published or charged.

Running studies​

Tools that change things need a key that can write, or a connection with Make changes. Observers can't use them. Each one does what the same button does in the app, and the workspace's audit log marks it via MCP. The quotes, lists, links and the board in this table only read.

ToolWhat it does
update_study_guide / update_screenerReplaces a study's interview guide, or its screener.
update_study_settingsChanges the question, language, number of people (drafts only), audience, automatic report, AI interview settings and recruiting filters or deadline.
rename_study / move_study_to_project / list_projectsRenames a study, or files it under a Library project.
duplicate_studyCopies a study as a new draft.
delete_studyDeletes a draft. Needs confirm: true. Studies that have been out are deleted in the app.
get_launch_quote / launch_studyThe price and any setup problems, then the launch. Costs money. Needs confirm: true and expectedTotalCents from the quote; if the price changed, nothing is charged. With no saved card you get a payment link for a person to open.
get_places_quote / add_placesAdds people to a study that is out. Costs money, with the same checks as a launch.
pause_study / resume_study / end_studyPauses, resumes or ends a study. Ending needs confirm: true.
list_participants / get_participantPeople in a study, with status, screener answers and consent. First names only, and no emails. Every tool shows participants by first name.
invite_participantsAdds your own people to a study by email. Emails them if the study is running. Needs confirm: true.
replace_sessionFlags a session with a reason. A replacement is recruited free.
get_recording_linksDownload links for a session's recordings. They stop working after an hour.
regenerate_readoutWrites the study report again from the current sessions.
list_clips / create_clipClips, and a new clip from a session's transcript.
list_reels / create_reelHighlight reels, and a new reel from a study's clips (optionally rendered to video).
get_boardA study's board with its lanes and clips.
create_report / update_reportStarts a report from studies and a template, or changes its title, summary or document.
start_swarm_runStarts a draft Swarm run. Needs confirm: true; an extra run past the included ones costs money and also needs acceptExtraCharge: true.

Not available through MCP: billing, team and members, workspace settings, SSO and SCIM, API keys, webhooks, pilot interviews and uploading Library files.

What a connection or key can do​

The server uses the same rules as the API. A connection or key acts as the person who made it, with their workspace role, up to Member rights, and only sees that workspace.

  • Read-only keys and connections without Make changes can use every tool that reads, and can ask Eva. They can't use the tools that change things. Eva can't change anything for them.
  • Observers can read and ask Eva, but can't use the tools that change things.
  • Revoking a key in Settings stops it at once, for the API and for MCP.
  • Revoking a connection in Settings → API & MCP → Connected stops its access and refresh tokens at once. The person who connected it or a workspace admin can revoke it.

Before Eva spends money or contacts people, she asks for approval in the app. The MCP tools that spend money or email people ask the assistant for confirm: true, and the paid ones for the total from their quote, so the assistant must show you the price and get your yes first.

The MCP server, like the API, comes with the Pro, Team and Scale plans. On Free you can't create a key or approve a connection, and keys and connections made on a paid plan stop working (402) until you upgrade again.

Calls to the MCP server count towards the workspace's API calls. They show as MCP in the Usage chart in Settings. Each key can send 600 requests a minute, and the workspace's monthly calls are the same as for the API.