> For the complete documentation index, see [llms.txt](https://learning.contextqa.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://learning.contextqa.com/mcp-server/installation-and-setup.md). # Installation & Setup Connect the ContextQA MCP Server to AI assistants like Claude, Claude Code, Cursor, ChatGPT, and Codex using OAuth 2.0. ## Quick answer Connect the ContextQA MCP Server to ChatGPT, Claude, Claude Code, Cursor, Codex, or another compatible client using OAuth 2.0. Eligible workspaces can open **Settings → MCP** for copyable client configuration and a credential-free ContextQA agent skill; verify the connection with a read-only request before authorizing changes. ## What this page covers {% hint style="info" %} **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. {% endhint %} ContextQA runs a **hosted MCP server** at `https://mcp.contextqa.com/mcp`. Configure a compatible client for the remote server and authenticate with your ContextQA account through OAuth 2.0. The tools available depend on the connected server and your account permissions. For repository testing workflows and client-specific tutorials, see [testing with AI coding agents](/testing-with-ai-coding-agents/ai-agent-testing.md). ## Use the in-product connection page Open **Settings → MCP** to reach **Connect ContextQA**. The page provides client-specific setup for ChatGPT, Claude, Claude Code, Cursor, and Codex, with copyable configuration for the supported methods. On smaller screens, the method labels shorten but the configuration and file location remain visible. The page also provides a ContextQA agent skill that you can download, inspect, or pair with a copyable agent prompt. The skill file does not contain ContextQA credentials; OAuth still controls the account and workspace available to the client. Eligible new workspaces can also see the same connection workflow during self-serve onboarding. Select the client, copy its configuration, and finish sign-in in the client. You can skip the onboarding step and return to **Settings → MCP** later without blocking workspace creation. ```mermaid flowchart LR A[Settings: MCP] --> B[Choose an AI client] B --> C[Copy configuration] A --> D[Inspect or download agent skill] C --> E[Complete ContextQA OAuth] D --> F[Install in the approved agent] E --> G[Run a read-only verification] F --> G ``` {% hint style="success" %} **Connection references:** Use [mcp.contextqa.com/docs](https://mcp.contextqa.com/docs) for the hosted endpoint and account connection guidance. Check the official documentation for your installed client and the authenticated tool manifest for current configuration, parameters, and available tools. {% endhint %} *** ## What you need * **A ContextQA account** — sign up at [contextqa.com](https://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 Complete the client's authentication action or browser sign-in prompt before relying on a tool call. The entry point differs by client (see [Authenticating](#authenticating)). ### Claude Code Add the server with a single command: ```bash claude mcp add --transport http contextqa https://mcp.contextqa.com/mcp ``` In an interactive Claude Code session, open `/mcp`, select ContextQA, and complete its authentication action. Then verify a read-only tool call. See the [Claude Code testing guide](/testing-with-ai-coding-agents/claude-code-testing.md) for the full workflow. ### 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` ```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: ```json { "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 ChatGPT calls MCP connections **apps**. Before adding ContextQA, an eligible workspace must allow custom apps and Developer mode: 1. In a **Business** workspace, a workspace owner or admin opens **Workspace settings → Apps**, enables Developer mode, and selects **Create**. 2. In an **Enterprise or Edu** workspace, an administrator first grants the appropriate app permissions. An authorized user then opens **Settings → Apps → Advanced settings**, enables Developer mode, and creates the app from **Apps**. 3. Enter the ContextQA MCP server URL: * **URL:** `https://mcp.contextqa.com/mcp` 4. Complete the ContextQA OAuth 2.0 sign-in. If the workspace requires review, an administrator must approve or publish the app before other members can use it. Once connected, ContextQA tools are available to ChatGPT in conversations where the app is enabled. OpenAI may change the labels as the feature evolves; use [OpenAI's current Developer mode and custom MCP app guide](https://help.openai.com/en/articles/12584461-developer-mode-apps-and-full-mcp-connectors-in-chatgpt-beta) as the authority for ChatGPT-specific availability and controls. {% hint style="info" %} Custom MCP apps are not available in every ChatGPT plan or workspace configuration. If **Developer mode**, **Create**, or custom apps are missing, confirm plan eligibility, workspace permissions, and administrator approval. This is a ChatGPT access issue, not a ContextQA server issue. {% endhint %} ### Codex Add and authenticate the server with the Codex CLI: ```bash codex mcp add contextqa --url https://mcp.contextqa.com/mcp codex mcp login contextqa codex mcp list ``` Alternatively, merge this remote-server entry into your Codex configuration, then run `codex mcp login contextqa`: ```toml # ~/.codex/config.toml [mcp_servers.contextqa] url = "https://mcp.contextqa.com/mcp" ``` Complete the browser login and verify a read-only ContextQA tool call. See the [Codex testing guide](/testing-with-ai-coding-agents/codex-testing.md) and [official Codex MCP reference](https://developers.openai.com/codex/mcp) for configuration and authentication details. ### Other MCP clients For another client that supports the required remote transport and OAuth flow, configure: * **URL:** `https://mcp.contextqa.com/mcp` * **Transport:** HTTP * **Authentication:** OAuth 2.0 *** ## Authenticating For client-specific configuration examples in VS Code, Gemini CLI, and Windsurf/Cascade, use [other coding agents](/testing-with-ai-coding-agents/other-coding-agents.md). Verify authentication and a read-only tool call in your own account. The hosted server authenticates with **OAuth 2.0** using your ContextQA login: 1. Use your client's login/connect action or follow its authentication prompt to open the 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. {% hint style="warning" %} 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. {% endhint %} 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](/mcp-server/authentication.md). *** ## 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](/mcp-server/tool-reference.md). *** ## Troubleshooting Start with the layered [MCP Connection Troubleshooting](/mcp-server/troubleshooting.md) runbook so you can distinguish service health, client configuration, OAuth, workspace scope, and manifest availability before changing the connection. | 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 | | Custom app or **Create** option missing (ChatGPT) | Plan, Developer mode, or workspace permission | Confirm plan eligibility, enable Developer mode in **Apps**, and ask a workspace administrator to grant or approve custom-app access | | 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](/ai-features/ai-test-generation.md) — understand the generation sources available via MCP tools * [Running Tests](/execution/running-tests.md) — how test execution works in ContextQA * [Environments](/execution/environments.md) — configure the environments your MCP-triggered tests run against * [Failure Analysis](/reporting/failure-analysis.md) — interpret the results returned by MCP analysis tools * [GitHub Actions](/integrations/github-actions.md) — combine MCP with CI/CD for automated test pipelines * [ContextQA for SDETs](/documentation-by-role/by-role/for-sdets.md) — role guide with MCP workflow patterns and architecture examples *** ## Next steps * [Official MCP docs](https://mcp.contextqa.com/docs) — the authoritative, always-current setup reference * [Authentication](/mcp-server/authentication.md) — detailed guide to the OAuth 2.0 sign-in flow and sessions * [MCP Connection Troubleshooting](/mcp-server/troubleshooting.md) — collect a safe diagnostic record and isolate the failing layer * [Agent Integration Guide](/mcp-server/agent-integration-guide.md) — how to structure AI agent workflows with these tools * [Tool Reference](/mcp-server/tool-reference.md) — full parameter documentation for every tool --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://learning.contextqa.com/mcp-server/installation-and-setup.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.