Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Authentication

How the ContextQA MCP Server authenticates AI clients with OAuth 2.0 — the sign-in flow, sessions, multiple accounts, and troubleshooting.

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

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 OAuth flow is for the MCP server only. To call the ContextQA REST API directly from a script, CI job, or integration, create an API token instead.

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.

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.

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.

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.

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 — connect Claude, Claude Code, Cursor, ChatGPT, or Codex to the hosted server

  • Agent Integration Guide — learn how to structure multi-step tool orchestration

  • Tool Reference — complete parameter documentation for all tools

PreviousInstallation & SetupNextTutorial: Your First Test with an AI Agent

Last updated

Was this helpful?