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.
- 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.
- Name it User Evaluation and enter
https://api.userevaluation.com/mcpas the URL. In ChatGPT, choose OAuth for authentication. - A User Evaluation page opens. Sign in if you need to.
- 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.
- 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.
- Go to Settings → API & MCP and create an API key. Tick Read only if the assistant only needs to read.
- Copy the key. It is shown only once.
- 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
401withWWW-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-resourceand/.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 behttps,httponlocalhost/127.0.0.1, or an app's own scheme, and must match exactly at/authorize. GET /authorizetakes the authorization code flow with PKCES256(required) and theresourceindicator (RFC 8707). The redirect back carriescode,stateandiss.POST /tokensupportsauthorization_codeandrefresh_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) andwrite(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
| Tool | What it does |
|---|---|
list_studies | Lists studies, newest first. Filter by status or type, or search with q. |
get_study | One study: question, guide, screener, audience and status. Takes an id or a slug. |
get_study_status | A study's status and progress: invited, booked, completed, quality, next session. |
list_sessions | A study's sessions, without transcripts. |
get_session | One session with its full transcript, chapters and signals. |
get_readout | The study report for a study: themes, claims with their clips, next steps. |
list_reports / get_report | Reports in the workspace, and one report with its document. |
list_swarm_runs | Swarm runs, newest first. |
list_findings / get_finding | The findings of a Swarm run, and one finding with its evidence. |
search | Finds studies, reports, chats, Library files, projects, Swarm runs and people by name. |
search_evidence | Searches what participants said: transcripts, clips, Library transcripts and study report claims. |
list_library_files / get_library_file | Library files, and one file with its transcript. |
ask_eva | Asks Eva. The answer cites its evidence and is saved as a chat in the app. |
create_draft_study | Drafts 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.
| Tool | What it does |
|---|---|
update_study_guide / update_screener | Replaces a study's interview guide, or its screener. |
update_study_settings | Changes 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_projects | Renames a study, or files it under a Library project. |
duplicate_study | Copies a study as a new draft. |
delete_study | Deletes a draft. Needs confirm: true. Studies that have been out are deleted in the app. |
get_launch_quote / launch_study | The 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_places | Adds people to a study that is out. Costs money, with the same checks as a launch. |
pause_study / resume_study / end_study | Pauses, resumes or ends a study. Ending needs confirm: true. |
list_participants / get_participant | People in a study, with status, screener answers and consent. First names only, and no emails. Every tool shows participants by first name. |
invite_participants | Adds your own people to a study by email. Emails them if the study is running. Needs confirm: true. |
replace_session | Flags a session with a reason. A replacement is recruited free. |
get_recording_links | Download links for a session's recordings. They stop working after an hour. |
regenerate_readout | Writes the study report again from the current sessions. |
list_clips / create_clip | Clips, and a new clip from a session's transcript. |
list_reels / create_reel | Highlight reels, and a new reel from a study's clips (optionally rendered to video). |
get_board | A study's board with its lanes and clips. |
create_report / update_report | Starts a report from studies and a template, or changes its title, summary or document. |
start_swarm_run | Starts 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.