Quickstart: coding agent with MCP

Use this path when you want to stay in your coding agent while QualityMax does the verification work. It takes you from a small, safe crawl to a generated Playwright test and an execution you can inspect.

Before you start

Create or sign in to your QualityMax account. Claude Code can use browser OAuth, so you do not need to create or copy a QualityMax API token.
Choose a public or dedicated test environment. Start with a narrow, read-only journey such as opening a page and submitting a harmless search. Do not use a production flow that creates, deletes, or charges anything.

1. Connect your client

Add the hosted connector from a regular terminal. Keep the command on one line:

claude mcp add-json qualitymax '{"type":"http","url":"https://app.qualitymax.io/api/mcp/","oauth":{"scopes":"mcp:read mcp:write"}}'

Then start Claude Code:

Run /mcp and select qualitymax.
Choose to authenticate. Claude Code opens QualityMax in your browser.
Sign in and review the Full testing access consent. This allows Claude to read test data, create or update test assets, and start crawls or test runs.
Approve only if those actions match your intent.
Return to Claude Code after the browser shows Authentication successful.

No access code, API token, Authorization header, or credential JSON needs to be copied. Claude Code stores and refreshes the OAuth credentials in its own secure storage.

If /mcp is an unknown command, restart Claude Code without --disable-slash-commands. You can also run claude mcp list in a regular terminal to confirm the server was added.

For project-level setup, use this credential-free OAuth .mcp.json:

{
  "mcpServers": {
    "qualitymax": {
      "type": "http",
      "url": "https://app.qualitymax.io/api/mcp/",
      "oauth": {
        "scopes": "mcp:read mcp:write"
      }
    }
  }
}

Use "scopes": "mcp:read" instead when you deliberately want reconnaissance-only access. If scopes are omitted, QualityMax also defaults the connection to read-only.

Alternative: Smithery

QualityMax MCP on Smithery provides a managed connection path with OAuth. Add it from your terminal:

npx -y smithery mcp add qualitymax/qualitymax-mcp

After the OAuth flow completes, inspect the available tools before asking your agent to run one:

npx -y smithery tool list qualitymax/qualitymax-mcp

Keep authentication details in the OAuth flow and your client’s secure storage. Do not paste credentials into a repository or chat. Start with the bounded, read-only request at the end of this section.

Static-token fallback for other clients

The hosted OAuth flow above is the default for Claude Code. For a client that does not support hosted MCP OAuth, create a token under Settings → API Tokens and keep it in private local configuration. Never commit it or paste it into chat.

Codex

Set a private environment variable named QUALITYMAX_CREDENTIAL to the token you created. Add this entry to ~/.codex/config.toml, then start a new Codex session:

[mcp_servers.qualitymax]
url = "https://app.qualitymax.io/api/mcp/"
bearer_token_env_var = "QUALITYMAX_CREDENTIAL"

Run /mcp in Codex and confirm that qualitymax is enabled.

Antigravity

In the agent panel, choose MCP Servers → Manage MCP Servers → View raw config. Add this entry to the existing mcpServers object in ~/.gemini/config/mcp_config.json (or the workspace-local .agents/mcp_config.json), replacing the placeholder only in your private copy:

{
  "mcpServers": {
    "qualitymax": {
      "serverUrl": "https://app.qualitymax.io/api/mcp/",
      "headers": {
        "Authorization": "Bearer <paste-your-token-here>"
      }
    }
  }
}

Save the file, return to Manage MCP Servers, and choose Refresh. Confirm that qualitymax appears as an installed server.

OpenCode

Set a private environment variable named QUALITYMAX_CREDENTIAL to the token you created. Add this entry to your opencode.json, then restart OpenCode:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "qualitymax": {
      "type": "remote",
      "url": "https://app.qualitymax.io/api/mcp/",
      "enabled": true,
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:QUALITYMAX_CREDENTIAL}"
      }
    }
  }
}

Run opencode mcp list and confirm that qualitymax is connected.

In your connected client, ask: “Use QualityMax to list my projects.” A successful response means the connection is ready. If tools do not appear, restart the client and confirm the connector URL includes the trailing slash in https://app.qualitymax.io/api/mcp/. For a static-token client, also check that its private token configuration is current.

2. Crawl a small journey and generate coverage

Give the agent one bounded request. Replace the example address and journey with your safe test target:

Use QualityMax to create or select a project for https://example.test.
Crawl only the public search journey, generate Playwright test cases and scripts for it,
and show me the generated test cases before running anything.

Review the returned test cases and generated scripts. Keep the first run small: one happy-path test with an assertion that matters to your users is a better starting point than a broad crawl.

3. Run the generated test

After you approve one generated script, ask:

Run the selected generated Playwright test with QualityMax. When it completes, report the
execution result and give me the available artifacts, including the trace when one was captured.

The agent waits for the execution result instead of treating “queued” as success. A passing run is your first checkpoint; a failed run is still useful evidence for refining the test or the target environment.

4. Inspect the evidence

Open the execution returned by the agent in QualityMax. Inspect its status, logs, and attached screenshots or video. Open the trace when the execution includes one. This is the handoff point: you have a generated test, a real result, and evidence another person can review.

Next, promote the reviewed test into your normal suite or continue with the web app quickstart to add a CI gate.