Documentation Index
Fetch the complete documentation index at: https://docs.autousers.ai/llms.txt
Use this file to discover all available pages before exploring further.
The Autousers MCP server lets you run UX evaluations without leaving your AI coding tool. Connect once and you can create evaluations, queue autousers against live URLs, read results, and calibrate personas — all from Claude, Cursor, VS Code, ChatGPT, or any MCP-aware client. The server is hosted at https://mcp.autousers.ai/mcp; no package installation is required for most clients.
Connect
Paste https://mcp.autousers.ai/mcp into your client’s MCP connector UI. OAuth 2.1 launches in the browser on first use — no API key needed for interactive sessions.| Client | How to connect |
|---|
| Claude.ai | Settings → Connectors → Add custom connector → paste URL |
| Claude Desktop | Settings → Connectors → Add custom connector → paste URL |
| Cursor | See config below |
| VS Code + Copilot | See config below |
| ChatGPT | Settings → Connectors → Developer Mode → Add connector → paste URL |
| Codex CLI | See config below |
~/.cursor/mcp.json:{
"mcpServers": {
"autousers": {
"url": "https://mcp.autousers.ai/mcp"
}
}
}
.vscode/mcp.json (workspace) or ~/.config/Code/User/mcp.json (global):{
"servers": {
"autousers": {
"type": "http",
"url": "https://mcp.autousers.ai/mcp"
}
}
}
claude mcp add --transport http autousers https://mcp.autousers.ai/mcp
codex mcp add autousers --url https://mcp.autousers.ai/mcp
For environments without a browser — CI pipelines, scripted workflows — run the server as a local stdio process using your API key.Pass your key as an environment variable in your client config:{
"mcpServers": {
"autousers": {
"command": "npx",
"args": ["-y", "@autousers/mcp"],
"env": {
"AUTOUSERS_API_KEY": "ak_live_..."
}
}
}
}
claude mcp add --transport http autousers https://mcp.autousers.ai/mcp \
--header "Authorization: Bearer $AUTOUSERS_API_KEY"
Clients that only support stdio — Cline, Zed, Continue, Goose — can connect via the mcp-remote shim.Generic stdio config (Cline and similar):{
"mcpServers": {
"autousers": {
"command": "npx",
"args": ["-y", "mcp-remote@>=0.1.16", "https://mcp.autousers.ai/mcp"]
}
}
}
~/.config/zed/settings.json:{
"context_servers": {
"autousers": {
"command": {
"path": "npx",
"args": ["-y", "mcp-remote@>=0.1.16", "https://mcp.autousers.ai/mcp"]
}
}
}
}
~/.continue/config.yaml:mcpServers:
- name: autousers
command: npx
args:
- -y
- "mcp-remote@>=0.1.16"
- https://mcp.autousers.ai/mcp
Authentication
OAuth is recommended for interactive sessions (Claude.ai, Claude Desktop,
Cursor, VS Code, ChatGPT). API keys are the right choice for CI pipelines and
headless scripts.
OAuth 2.1
When you add the server URL to a supported client, an OAuth 2.1 PKCE flow launches in the browser. After you approve, the client receives a short-lived access token (~15 minutes) that rotates automatically via a refresh token. No static credentials are stored on the client.
API keys
API keys are long-lived bearer tokens for headless environments. Pass them as Authorization: Bearer ak_live_... — either as an HTTP header in direct-URL clients or as the AUTOUSERS_API_KEY environment variable for stdio.
Mint keys at app.autousers.ai/settings/api-keys. Keys are shown once at creation — store them in a secrets manager immediately.
Scopes
| Scope | Grants |
|---|
templates:read | List and fetch templates |
templates:write | Create, update, delete, duplicate templates |
evaluations:read | List, fetch, export, view results |
evaluations:write | Create, update, delete, share evaluations |
autousers:read | List autousers, fetch runs and telemetry |
autousers:write | Create, update, delete, run, calibrate autousers |
ratings:read | List ratings for an evaluation |
webhooks:read | List endpoints, deliveries, and inspect signatures |
webhooks:write | Create, rotate, retry, and delete webhook endpoints |
events:read | List the event log feeding webhook deliveries |
readOnlyHint=true and are safe to call without side effects.
Templates (6)
| Tool | Description |
|---|
templates_list | List question templates available to your team |
templates_get | Fetch a single template by ID |
templates_create | Create a new team-scoped template |
templates_update | Patch a template (only supplied fields change) |
templates_delete | Hard-delete a template |
templates_duplicate | Deep-clone a template into a destination team |
Evaluations (14)
| Tool | Description |
|---|
evaluations_list | List evaluations the caller can see |
evaluations_get | Fetch one evaluation including config and comparisons |
evaluations_create | Create an SSE or SxS evaluation; optionally queue autouser runs |
evaluations_update | Patch fields on an evaluation |
evaluations_delete | Delete an evaluation and its dependent rows |
evaluations_save_draft | Merge wizard fields into a draft evaluation |
evaluations_ratings_list | List human and autouser ratings |
evaluations_results_get | Aggregate stats and per-rater summaries |
evaluations_agreement_get | Pairwise Cohen’s Kappa inter-rater agreement |
evaluations_ai_insights_get | AI-authored summary, key findings, and recommendations |
evaluations_export_get | Download results as JSON or CSV |
evaluations_share_create | Grant a per-user VIEWER / EDITOR / OWNER share |
evaluations_shares_list | List explicit per-user shares |
evaluations_transfer | Transfer evaluation ownership to another user |
Autousers (15)
| Tool | Description |
|---|
autousers_list | List autousers (built-in + custom) |
autousers_get | Fetch a single autouser by ID |
autousers_create | Create a team-scoped custom autouser |
autousers_update | Patch a custom autouser |
autousers_delete | Soft-delete a custom autouser |
autousers_duplicate | Deep-clone an autouser into a team |
autousers_run | Queue autouser runs against an evaluation |
autousers_run_stop | Cancel pending or running autouser runs |
autouser_status_get | Run statuses and summary counts for an evaluation |
autouser_run_get | Fetch one autouser run with full context |
autouser_run_turns_list | Per-turn token and cost telemetry for a run |
autousers_calibration_start | Compute Cohen’s Kappa vs human ratings |
autousers_calibration_status_get | Get calibration status |
autousers_calibration_freeze | Freeze a rubric version and set it as active |
autousers_calibration_optimize | Send disagreements to AI for rubric suggestions |
Settings (4)
| Tool | Description |
|---|
teams_list | List every team the caller belongs to |
teams_get | Fetch one team’s detail |
team_members_list | List team members with roles and profiles |
usage_get | Usage rollup: free-run pool remaining and token spend |
Prompts
Five canned workflows are registered as MCP prompts. Invoke them from your client’s slash menu — the server pre-fetches relevant data and guides the AI through each workflow end-to-end.
| Prompt | Description |
|---|
evaluate-url | Create an SSE evaluation against a URL and surface results |
compare-designs | Create an SxS evaluation between two URLs |
analyze-results | Summarise evaluation results with key findings |
calibrate-autouser | Run calibration and freeze the rubric when stable |
triage-low-agreement | Surface autouser/human disagreements and suggest fixes |
Resources
Three readable resource URIs let your AI client fetch structured data directly:
| URI | Description |
|---|
autousers://evaluation/{id} | Full evaluation object including results |
autousers://template/{id} | Template definition with all dimensions |
autousers://autouser/{id} | Autouser persona with rubric |
Configuration
| Variable | Default | Description |
|---|
AUTOUSERS_API_KEY | — | Bearer token for headless/stdio auth (ak_live_...) |
AUTOUSERS_BASE_URL | https://app.autousers.ai | Override the API host (for self-hosted or local dev) |
Diagnostics
Run the bundled doctor command to verify your configuration:
npx -y -p @autousers/mcp autousers-mcp-doctor
AUTOUSERS_API_KEY is set (for stdio auth), that the API host is reachable, and that at least one tool call succeeds. The command exits non-zero on any misconfiguration, so it integrates cleanly into CI pre-flight checks.
