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.

This page is written for an AI coding agent. To use it, paste the prompt from MCP Server 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 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:

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.

{
  "mcpServers": {
    "qatech": {
      "type": "http",
      "url": "https://api.qa.tech/v1/mcp"
    }
  }
}

Codex. Run:

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. Runs, tests, and results are visible there too, and the in-app chat can do everything above. See MCP Server for the full list of tools.