> 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 AI assistants like Claude, Claude Code, Cursor, ChatGPT, and Codex using OAuth 2.0. Follow the documented prerequisites and steps, then verify the expected result before using the workflow in a shared or production process. ## 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`. 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. {% hint style="success" %} **Official reference:** The authoritative, always-current setup guide lives at [mcp.contextqa.com/docs](https://mcp.contextqa.com/docs). This page mirrors that guide for the GitBook docs; when the two differ, the official docs take precedence. {% 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 The first time a client calls a ContextQA tool, your browser opens the ContextQA login page (see [Authenticating](#authenticating)). ### Claude Code Add the server with a single command: ```bash 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` ```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 the server to your Codex configuration as a remote MCP server pointing at the hosted URL: ```toml # ~/.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. {% 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` 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 optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.