> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qa.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Quickstart

> Instructions for a coding agent (Claude Code, Cursor, Codex) to sign the user up for QA.tech, connect the QA.tech MCP server, and run the first tests.

> [!NOTE]
>
> This page is written for an AI coding agent. To use it, paste the prompt from
> [MCP Server](https://docs.qa.tech/integrations/mcp.md#set-up-with-your-agent) into Claude Code,
> Cursor, or Codex.

You are setting up QA.tech for the user. QA.tech runs AI agents that test the user's web app in a real browser. You will connect to it through the QA.tech MCP server at `https://api.qa.tech/v1/mcp`.

Follow the steps in order. Stop and wait for the user whenever a step needs them to act in a browser. Do not ask the user for passwords, API keys, or tokens.

## 1. Get the user an account

Ask the user if they already have a QA.tech account.

* **Yes:** skip to step 2.
* **No:** ask them to open [https://app.qa.tech/auth/sign-up](https://app.qa.tech/auth/sign-up) in their browser, create an account, and finish onboarding. Onboarding asks for an organization name and then creates the first project from the URL of the app they want to test. Wait until they confirm they are done.

If the user prefers, they can skip this step: signing in from the MCP client in step 3 also offers sign-up, runs onboarding, and returns to the authorization screen.

## 2. Add the MCP server

Use the command for the client you are running in. The server name is `qatech`.

**Claude Code.** Run:

```bash theme={null}
claude mcp add --transport http qatech https://api.qa.tech/v1/mcp
```

**Cursor.** Add this entry to `~/.cursor/mcp.json`. Merge it into the existing `mcpServers` object if the file already exists; do not remove other servers.

```json theme={null}
{
  "mcpServers": {
    "qatech": {
      "type": "http",
      "url": "https://api.qa.tech/v1/mcp"
    }
  }
}
```

**Codex.** Run:

```bash theme={null}
codex mcp add qatech --url https://api.qa.tech/v1/mcp
```

If Codex reports that remote MCP servers are not enabled, add `experimental_use_rmcp_client = true` under `[features]` in `~/.codex/config.toml` and run the command again.

## 3. Sign in

The server uses OAuth. The user signs in to QA.tech in their browser and approves access. Tell the user exactly what to do:

* **Claude Code:** run `/mcp`, select `qatech`, and choose authenticate. Or run `claude mcp login qatech` in a terminal.
* **Cursor:** open **Settings → Cursor Settings → Tools & MCPs** and click the sign-in prompt next to `qatech`.
* **Codex:** run `codex mcp login qatech`.

On the QA.tech consent screen, the user picks the organization and the projects you may use. Ask them to allow the project they want to test, or all projects if you will create one.

The QA.tech tools may not appear in the current session. If they are missing after sign-in, ask the user to restart or reload the client (for Claude Code, restart `claude`; for Cursor, reload the window; for Codex, start a new session), then continue from step 4.

## 4. Verify the connection

Call `list_projects`.

* **The call fails or the tool is missing:** go back to step 3.
* **One or more projects:** pick the one whose URL matches the app in this repository. Ask the user if it is unclear. Use its `shortId` as `projectShortId` in every later call.
* **No projects:** call `create_project` with a `name` and the `url` of the app to test. Find the URL in the repository (deploy config, README, `.env.example`, staging or preview URLs). If you cannot find a reachable URL, ask the user. QA.tech tests run in the cloud, so `localhost` does not work. Use the returned `project.shortId`.

## 5. Teach QA.tech about the app

Read the codebase and save durable facts that help the testing agent. Call `create_knowledge_item` with `type: "text"`, a short `title`, and the facts as `content`. Good items:

* **App structure:** main pages and routes, the core user flows, roles and what each can do.
* **Test accounts:** usernames and passwords from seed, fixture, or example config files that are meant for testing (for example `seed.sql`, `fixtures/`, `.env.example`). Say which environment they work on.
* **Feature flags:** flags that change what the UI shows, and their default values.
* **Gotchas:** sign-up email verification, captchas, rate limits, or third-party flows the agent should expect.

Never save real production secrets: no values from `.env`, `.env.local`, or `.env.production`, no live API keys, and no personal credentials. If you are unsure whether a value is a secret, leave it out and mention it to the user.

Call `list_knowledge_items` first and skip facts that are already there.

## 6. Run the first tests

Call `list_test_cases` for the project.

* **Tests exist:** call `start_run_with_test_cases` with their IDs as `testCaseIds` (or `start_run_with_test_plan` if the user has a test plan). Poll `get_run` with the returned `run.shortId` until it reaches a terminal status. Wait at least a few seconds between polls.
* **No tests:** call `create_chat` and ask the QA.tech agent to create and run one test for the app's main flow, for example: "Create a test that signs in with the test account and completes the main flow: ...". Poll `get_chat_conversation` until `status` is `completed`, `failed`, or `cancelled`, then call `get_run` with `runs[].shortId`. Prefer `create_chat` over `create_test_case`: the QA.tech agent explores the site first, so the test matches what actually exists.

When the run finishes, report the result: which tests passed or failed and, for failures, the reason from `get_run_test_case`.

If the run fails because the agent cannot reach the app or sign in, fix the cause (wrong URL, missing test account, IP allowlist) with the user and run again.

## 7. Tell the user what they can do now

Finish with a short summary of what you set up (account, MCP server, project, knowledge items, first run and its result). Then tell the user they can ask you to:

* Run the tests, or only the tests related to the change they are working on.
* Read why a test failed, with screenshots and logs, and fix the bug in the code.
* Rerun failed tests after a fix (`rerun_run`).
* Add tests for a new feature or a bug they just fixed.
* Save more knowledge about the app, such as new test accounts or flows.

The dashboard is at [https://app.qa.tech](https://app.qa.tech). Runs, tests, and results are visible there too, and the in-app chat can do everything above. See [MCP Server](https://docs.qa.tech/integrations/mcp.md) for the full list of tools.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.