Connect to ArtificialQA via MCP

Which path do I use?

OAuth setup (recommended)

You need mcp-remote installed once on your machine. It's the small proxy that bridges your client's stdio transport to ArtificialQA's HTTP endpoint and handles the browser OAuth flow.

npm install -g mcp-remote

Then paste this into your client's config file:

{
  "mcpServers": {
    "artificialqa": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://app.artificialqa.com/api/v1/mcp"
      ]
    }
  }
}

Where the config file lives

What happens on first connect

1. You launch your MCP client (e.g. quit + relaunch Claude Desktop after editing the config).
2. mcp-remote discovers ArtificialQA's auth server.
3. Your default browser opens at /oauth/authorize.
4. If you're not already signed in to ArtificialQA in that browser, you're sent to /login. Sign in (and pass 2FA if your account requires it).
5. You're back at a consent screen: pick the project you want the client to act on, pick Read only or Read + write (your role on the project is the ceiling), click Allow.
6. The browser shows a branded "Authorization successful" page. You can close the tab.
7. Your MCP client now shows the server as connected. Try list_test_plans or list_test_cases to confirm.

After this, mcp-remote caches your tokens in ~/.mcp-auth/ and rotates them automatically. You won't see the browser again for ~30 days, or until you revoke the session.

Windows note

If npx -y mcp-remote fails with 'C:\Program' is not recognized, that's cmd /C choking on the space inside C:\Program Files\nodejs\npx.cmd. Point at the shim under %APPDATA%\Roaming\npm\ directly:

{
  "mcpServers": {
    "artificialqa": {
      "command": "C:\\Users\\<you>\\AppData\\Roaming\\npm\\mcp-remote.cmd",
      "args": ["https://app.artificialqa.com/api/v1/mcp"]
    }
  }
}

"No accessible projects" / "No organizations"

You hit one of the consent-screen error states. Common causes:

Close the tab, sign out from the dropdown, sign in as the right account, and restart your MCP client to re-trigger the flow.

Static API key setup (admin-provisioned)

If your org admin has given you an aqa_* key, paste this instead:

{
  "mcpServers": {
    "artificialqa": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://app.artificialqa.com/api/v1/mcp",
        "--header",
        "Authorization: Bearer aqa_v0C5AyynN..."
      ]
    }
  }
}

The only difference vs the OAuth snippet is the --header Authorization: Bearer ... flag at the end. No browser flow on first connect — the key authenticates you immediately. The key is bound to one project, so the client only ever sees data inside that project.

Native HTTP clients (Cursor without stdio)

Cursor and Continue can also speak Streamable HTTP directly, without mcp-remote. Same idea, different config shape:

{
  "mcpServers": {
    "artificialqa": {
      "url": "https://app.artificialqa.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer aqa_v0C5AyynN..."
      }
    }
  }
}

Native HTTP only works with static keys — Cursor and Continue don't run the OAuth handshake on their own. If you want OAuth on those clients, use the stdio snippet above and let mcp-remote handle the flow.

Verifying the connection (curl)

You don't need a client to confirm the endpoint is reachable. With a static key:

curl https://app.artificialqa.com/api/v1/mcp \
  -X POST \
  -H "Authorization: Bearer aqa_v0C5AyynN..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Expect a result.tools array listing every tool you have access to. A 401 with a WWW-Authenticate header means the key was rejected (check the value, and that your org has MCP enabled). A 403 with mcp_disabled means the org admin needs to flip the MCP feature flag.

OAuth tokens (oat_*) work the same way for curl, but you have to extract one from the cache mcp-remote writes — there is no UI to copy your access token, because the whole point is that you never see it.

Frequently hit issues

"Authorization successful" never appears, browser hangs at consent. The MCP client likely timed out (~60s for the initial handshake). Quit and relaunch your MCP client to restart the flow with a fresh mcp-remote process. Have your password and TOTP ready so the browser flow finishes well under 60s.

Tab keeps opening every time I launch the client. mcp-remote couldn't write its cache. Check that ~/.mcp-auth/ is writable by your user. On macOS, sometimes the Claude Desktop sandbox needs to be re-granted access to the home directory.

"redirect_uri not registered for this client". mcp-remote's registered redirect URI no longer matches the port it's listening on (usually after a manual cache wipe). Clear the cache and let it re-register:

rm -rf ~/.mcp-auth                                          # macOS / Linux
Remove-Item -Recurse -Force "$env:USERPROFILE\.mcp-auth"   # Windows PowerShell

Then relaunch the MCP client.

'C:\Program' is not recognized on Windows. See the Windows note in the OAuth setup section above — use the .cmd shim path instead of npx.

Reference

• Public REST API reference — the same primitives over a REST surface for CI/CD.
• Integrations — how MCP fits with the broader integration story.
• Security & compliance — audit semantics, scope ceilings, and break-glass revocation.