Installation & Setup

Connect the ContextQA MCP Server to AI assistants like Claude, Claude Code, Cursor, ChatGPT, and Codex using OAuth 2.0.

Who is this for? SDETs, developers, and anyone who wants to drive ContextQA from an AI assistant such as Claude, Claude Code, Cursor, ChatGPT, or Codex.

ContextQA runs a hosted MCP server at https://mcp.contextqa.com/mcp. You don't install or run anything — point your MCP-compatible client at the server URL, sign in with your ContextQA account through OAuth 2.0, and your AI assistant can drive the full ContextQA toolset. Connecting takes under 5 minutes.

Official reference: The authoritative, always-current setup guide lives at mcp.contextqa.com/docs. This page mirrors that guide for the GitBook docs; when the two differ, the official docs take precedence.

---

What you need

• A ContextQA account — sign up at contextqa.com if you don't have one. You sign in to the MCP server with this account through OAuth 2.0.
• An MCP-compatible client — Claude Code, Claude Desktop, Cursor, ChatGPT, Codex, or any client that supports a remote MCP server over HTTP.

The hosted server uses HTTP transport and OAuth 2.0 authentication, so there is nothing to download, no local process to keep running, and no API keys to manage.

---

Connecting your client

Every client connects to the same hosted server:

• URL: https://mcp.contextqa.com/mcp
• Transport: HTTP
• Authentication: OAuth 2.0

The first time a client calls a ContextQA tool, your browser opens the ContextQA login page (see Authenticating).

Claude Code

Add the server with a single command:

claude mcp add --transport http contextqa https://mcp.contextqa.com/mcp

The next time you use a ContextQA tool, Claude Code opens a browser login.

Claude Desktop

Open (or create) the Claude Desktop config file and add the server URL:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "contextqa": {
      "url": "https://mcp.contextqa.com/mcp"
    }
  }
}

Restart Claude Desktop after saving. A hammer icon in the input bar indicates that the ContextQA tools are available.

Cursor

Edit ~/.cursor/mcp.json and add the server:

{
  "mcpServers": {
    "contextqa": {
      "url": "https://mcp.contextqa.com/mcp"
    }
  }
}

Then open Tools & MCP in Cursor settings and click Connect next to the contextqa server. Cursor opens a browser to complete the OAuth 2.0 sign-in.

ChatGPT

In ChatGPT, open Settings → Connectors, add a custom connector, and enter the server URL:

• URL: https://mcp.contextqa.com/mcp

ChatGPT opens a browser to complete the OAuth 2.0 sign-in. Once connected, the ContextQA tools are available to the assistant.

Custom MCP connectors in ChatGPT require a plan and workspace setting that allows them. If you don't see the option to add a connector, check with your workspace administrator.

Codex

Add the server to your Codex configuration as a remote MCP server pointing at the hosted URL:

# ~/.codex/config.toml
[mcp_servers.contextqa]
url = "https://mcp.contextqa.com/mcp"

The first ContextQA tool call opens a browser to complete the OAuth 2.0 sign-in.

Other MCP clients

For any other client, configure a remote MCP server with:

• URL: https://mcp.contextqa.com/mcp
• Transport: HTTP
• Authentication: OAuth 2.0

---

Authenticating

The hosted server authenticates with OAuth 2.0 using your ContextQA login:

1. The first time your client calls a ContextQA tool, your browser opens a ContextQA login page.
2. Sign in with your ContextQA account.
3. Wait for the callback to finish and the browser to auto-redirect back to your client.

Don't close the browser or navigate away until the redirect completes. If you interrupt the callback, authorization with the MCP server fails and you must start the login again.

Access tokens last 8 hours and refresh automatically, so you stay signed in across a normal working day without re-authenticating. For multi-account and session details, see Authentication.

---

Verifying the connection

Once your client connects and you have signed in, the ContextQA tools appear in the client's tool list. You don't call the tools directly — describe what you want in plain English, and your AI assistant selects the appropriate tool, fills in the parameters, and returns the results.

Try a prompt such as:

List my most recent test cases in ContextQA.

If the assistant returns your test cases, the connection works. If you are prompted to sign in again, complete the OAuth flow and retry.

---

Available capabilities

The hosted server exposes ContextQA's full test-automation toolset, grouped into categories you can drive from natural-language prompts:

Category	What you can do
Test cases	Create, list, update, delete, and search test cases
Test generation	Generate tests from diffs, tickets, Figma, Swagger, videos, Excel, and n8n workflows
Execution & results	Run tests, poll status, and fetch results and step details
Suites & plans	Manage test suites and plans, environments, and devices
Debugging	Pull network logs, console logs, traces, and root cause analysis
Bug fix	Run the reproduce → investigate → verify → report workflow
Code export	Export to Playwright or Cypress and migrate existing repositories
AI insights	Analyze activity, detect coverage gaps, and get recommendations
Knowledge bases	Apply custom prompts to test generation and execution

For the full per-tool parameter documentation, see the Tool Reference.

---

Troubleshooting

Problem	Likely cause	Fix
Browser login never completes	Redirect interrupted	Restart the OAuth flow and wait for the browser to auto-redirect back before switching away
Tools prompt for sign-in repeatedly	Token expired or refresh blocked	Complete the OAuth login again; ensure your browser allows the ContextQA callback
Tools not appearing in the client	Config file syntax error	Validate the JSON in your client config with a JSON linter, then reconnect
Connector option missing (ChatGPT)	Plan or workspace setting	Confirm your plan supports custom MCP connectors and check with your workspace administrator
Sign-in fails	Wrong ContextQA account	Verify you are signing in with valid ContextQA credentials

---

Related documentation

Now that you've connected the MCP server, explore the platform features you can control through it:

• AI Test Generation — understand the generation sources available via MCP tools
• Running Tests — how test execution works in ContextQA
• Environments — configure the environments your MCP-triggered tests run against
• Failure Analysis — interpret the results returned by MCP analysis tools
• GitHub Actions — combine MCP with CI/CD for automated test pipelines
• ContextQA for SDETs — role guide with MCP workflow patterns and architecture examples

---

Next steps

• Official MCP docs — the authoritative, always-current setup reference
• Authentication — detailed guide to the OAuth 2.0 sign-in flow and sessions
• Agent Integration Guide — how to structure AI agent workflows with these tools
• Tool Reference — full parameter documentation for every tool