> 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/authentication.md). # Authentication {% hint style="info" %} **Who is this for?** SDETs, developers, and anyone connecting an AI assistant such as Claude, Claude Code, Cursor, ChatGPT, or Codex to ContextQA. {% endhint %} The hosted ContextQA MCP Server at `https://mcp.contextqa.com/mcp` authenticates with **OAuth 2.0**. You sign in once with your ContextQA account through your browser, and your client receives an access token it uses for every tool call. There are no API keys to manage and no credentials to store in your client configuration. This page explains how the sign-in flow works, how sessions and tokens behave, how to work with more than one account, and how to resolve common authentication problems. *** ## How sign-in works The first time your client calls a ContextQA tool, it triggers the OAuth 2.0 flow: 1. Your client opens a ContextQA login page in your browser. 2. You sign in with your **ContextQA account**. 3. ContextQA asks you to authorize the client's access. 4. The browser **auto-redirects back** to your client, which receives an access token. 5. Your client uses that token for every subsequent tool call. {% 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 sign-in again. {% endhint %} You only complete this flow when you first connect or after a token can no longer be refreshed. Day to day, sign-in is automatic. *** ## Sessions and tokens * **Access tokens last 8 hours.** Within that window, tool calls succeed without any further interaction. * **Tokens refresh automatically.** Your client renews the token in the background, so you stay signed in across a normal working day without re-authenticating. * **No credentials are stored in your client config.** Only the OAuth tokens are kept by your client; your ContextQA password is never written to a config file or transmitted to your AI provider. When a token expires and can't be refreshed — for example, after a long period of inactivity — your client prompts you to sign in again through the same browser flow. *** ## Using more than one account Each MCP client connection is tied to the account you sign in with. To switch accounts: 1. Disconnect the `contextqa` server in your client (or remove and re-add it). 2. Reconnect and complete the OAuth flow with the other account. To use different accounts at the same time — for example, a personal account and a team service account — configure the ContextQA server twice in your client under different names (such as `contextqa` and `contextqa-team`) and sign in to each separately. {% hint style="info" %} For CI/CD or shared automation, create a dedicated ContextQA account rather than using a personal login. This keeps audit logs clean and lets you revoke automation access independently. {% endhint %} *** ## Signing out To end a session, disconnect or remove the `contextqa` server from your client. This discards the stored tokens. The next time you add the server and call a tool, you complete the OAuth flow again. *** ## 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 | | Prompted to sign in repeatedly | Token can't be refreshed | Complete the OAuth login again; ensure your browser allows the ContextQA callback | | Authorization fails after login | Wrong ContextQA account or revoked access | Sign in with a valid ContextQA account that has access to your workspace | | Tools never appear after connecting | Client didn't trigger the OAuth flow | Call a ContextQA tool (for example, ask the assistant to list your test cases) to start the sign-in | | Connector option missing (ChatGPT) | Plan or workspace setting | Confirm your plan supports custom MCP connectors and check with your workspace administrator | *** ## Next steps * [Installation & Setup](/mcp-server/installation-and-setup.md) — connect Claude, Claude Code, Cursor, ChatGPT, or Codex to the hosted server * [Agent Integration Guide](/mcp-server/agent-integration-guide.md) — learn how to structure multi-step tool orchestration * [Tool Reference](/mcp-server/tool-reference.md) — complete parameter documentation for all tools --- # 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/authentication.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.