> 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 {% 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 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. {% hint style="info" %} 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. {% 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 | 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](/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 * [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.