> ## 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.

# MCP server

> The Autousers MCP server exposes 39 tools so you can create evaluations, run autousers, and read results directly from any MCP-aware AI client.

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

<Tabs>
  <Tab title="Direct URL (recommended)">
    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** — `~/.cursor/mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "autousers": {
          "url": "https://mcp.autousers.ai/mcp"
        }
      }
    }
    ```

    **VS Code + GitHub Copilot** — `.vscode/mcp.json` (workspace) or `~/.config/Code/User/mcp.json` (global):

    ```json theme={null}
    {
      "servers": {
        "autousers": {
          "type": "http",
          "url": "https://mcp.autousers.ai/mcp"
        }
      }
    }
    ```

    **Claude Code CLI**:

    ```bash theme={null}
    claude mcp add --transport http autousers https://mcp.autousers.ai/mcp
    ```

    **Codex CLI**:

    ```bash theme={null}
    codex mcp add autousers --url https://mcp.autousers.ai/mcp
    ```
  </Tab>

  <Tab title="Stdio (CI/headless)">
    For environments without a browser — CI pipelines, scripted workflows — run the server as a local stdio process using your API key.

    ```bash theme={null}
    npx -y @autousers/mcp
    ```

    Pass your key as an environment variable in your client config:

    ```json theme={null}
    {
      "mcpServers": {
        "autousers": {
          "command": "npx",
          "args": ["-y", "@autousers/mcp"],
          "env": {
            "AUTOUSERS_API_KEY": "ak_live_..."
          }
        }
      }
    }
    ```

    Or pass it as a Bearer header when using the direct URL with Claude Code:

    ```bash theme={null}
    claude mcp add --transport http autousers https://mcp.autousers.ai/mcp \
      --header "Authorization: Bearer $AUTOUSERS_API_KEY"
    ```
  </Tab>

  <Tab title="Bridge (stdio-only clients)">
    Clients that only support stdio — Cline, Zed, Continue, Goose — can connect via the [mcp-remote](https://github.com/geelen/mcp-remote) shim.

    **Generic stdio config** (Cline and similar):

    ```json theme={null}
    {
      "mcpServers": {
        "autousers": {
          "command": "npx",
          "args": ["-y", "mcp-remote@>=0.1.16", "https://mcp.autousers.ai/mcp"]
        }
      }
    }
    ```

    **Zed** — `~/.config/zed/settings.json`:

    ```json theme={null}
    {
      "context_servers": {
        "autousers": {
          "command": {
            "path": "npx",
            "args": ["-y", "mcp-remote@>=0.1.16", "https://mcp.autousers.ai/mcp"]
          }
        }
      }
    }
    ```

    **Continue** — `~/.continue/config.yaml`:

    ```yaml theme={null}
    mcpServers:
      - name: autousers
        command: npx
        args:
          - -y
          - "mcp-remote@>=0.1.16"
          - https://mcp.autousers.ai/mcp
    ```
  </Tab>
</Tabs>

## Authentication

<Note>
  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.
</Note>

### 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](https://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       |

## Tools

The server exposes 39 tools across four categories. Read-only tools carry `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:

```bash theme={null}
npx -y -p @autousers/mcp autousers-mcp-doctor
```

It checks that `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.