Authentication

Who is this for? SDETs, developers, and DevOps engineers integrating ContextQA with AI coding assistants (Claude, Cursor) or CI/CD pipelines.

The ContextQA MCP Server authenticates to the ContextQA platform using your account username and password. Every tool call triggers a fresh authentication against the ContextQA login API, which returns a session token used for that single request. There is no persistent session or token cache — this ensures credentials are always validated and never become stale.

This page explains how to supply credentials, in what order the server resolves them, how errors are surfaced, and how to configure different deployment scenarios.

---

Credential Sources

The server resolves credentials in the following priority order. A higher-priority source always overrides a lower one.

1. Query Parameters (Highest Priority — Per-Request)

You can pass credentials directly in the request URL. This is useful for multi-tenant deployments where different agents use different accounts, or for testing without restarting the server.

GET /mcp/[email protected]&CONTEXTQA_PASSWORD=mypassword

Because these are per-request parameters, they override any credentials set at the process or file level for that specific call only.

When to use this: CI pipelines where different jobs test different environments with different accounts, or multi-tenant SaaS deployments where each customer's requests carry their own credentials.

Security note: Query parameters appear in server access logs. For production deployments, prefer environment variables or secrets management over query parameters.

2. Environment Variables (Process-Level)

Set these before starting the server. They apply to all requests that do not supply per-request credentials.

export CONTEXTQA_USERNAME=[e-mail]
export CONTEXTQA_PASSWORD=yourpassword
python -m app.fastmcp_server

For Docker:

docker run -e [email protected] \
           -e CONTEXTQA_PASSWORD=yourpassword \
           contextqa-mcp

For docker-compose, add them to the environment section of your service definition, or use an env file reference.

3. .env File (Lowest Priority — Development Convenience)

Create a .env file in the project root directory. The server loads it automatically via python-dotenv when the process starts.

# cqa-mcp/.env
[email protected]
CONTEXTQA_PASSWORD=yourpassword

The .env file is loaded once at startup. Changes to the file require a server restart to take effect.

Do not commit .env files to version control. The repository's .gitignore already excludes .env by default.

---

How Authentication Works Internally

Each tool call goes through the following sequence:

1. The MCP server receives a tool call request

2. It resolves credentials from the priority chain above

3. It instantiates a ContextQAClient with those credentials

4. The client POSTs to the ContextQA login API:

   POST https://api.contextqa.com/auth/login
   {"username": "[email protected]", "password": "yourpassword"}

5. The login API returns a session token

6. The client uses that token as a Bearer token for the actual API call:

   Authorization: Bearer <session_token>

7. The API response is returned to the MCP caller

Sessions are not cached. Every tool call authenticates independently. This means:

• Rotating your ContextQA password takes effect on the next tool call with no server restart required (when using env vars that you update)

• There are no stale token issues in long-running server processes

• Each tool call incurs one additional login network round-trip (typically under 100ms)

---

Authentication Error Handling

If credentials are missing, empty, or incorrect, every tool call returns a structured error:

{
  "error": "Authentication failed: CONTEXTQA_USERNAME and CONTEXTQA_PASSWORD must be set correctly."
}

The server will not crash or enter an error state — it continues running and will succeed on subsequent requests once valid credentials are provided.

Common causes of authentication failure:

• CONTEXTQA_USERNAME or CONTEXTQA_PASSWORD environment variables are not set

• The .env file exists but is not in the project root directory

• The password contains special characters that were not properly quoted in the shell (export CONTEXTQA_PASSWORD='p@$$word!')

• The ContextQA account password was changed after the server started (update the env var and restart, or use the .env file approach with a restart)

• Incorrect email address (check for typos, extra spaces)

---

Configuration by Deployment Scenario

Claude Desktop — Local uv Install

Open ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) and add:

{
  "mcpServers": {
    "contextqa": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/cqa-mcp", "run", "mcp-contextqa"],
      "env": {
        "CONTEXTQA_USERNAME": "[email protected]",
        "CONTEXTQA_PASSWORD": "yourpassword"
      }
    }
  }
}

The env block in Claude Desktop's config injects these values as environment variables into the server process. They are stored in the config file on your local machine and are not transmitted to Anthropic.

Claude Desktop — Remote Server (Docker or Cloud Run)

When the MCP server is hosted remotely, Claude Desktop connects to it over HTTP rather than spawning a local process. Credentials are not needed in the Claude Desktop config because they are already embedded in the remote server's environment.

{
  "mcpServers": {
    "contextqa": {
      "url": "https://YOUR_CLOUD_RUN_URL/mcp"
    }
  }
}

If you want the client to pass credentials per-request (for multi-user scenarios), you can pass them as HTTP headers:

{
  "mcpServers": {
    "contextqa": {
      "url": "https://YOUR_CLOUD_RUN_URL/mcp",
      "headers": {
        "X-ContextQA-Username": "[email protected]",
        "X-ContextQA-Password": "yourpassword"
      }
    }
  }
}

Cursor

In Cursor's MCP settings, the configuration follows the same format as Claude Desktop:

{
  "contextqa": {
    "command": "uv",
    "args": ["--directory", "/absolute/path/to/cqa-mcp", "run", "mcp-contextqa"],
    "env": {
      "CONTEXTQA_USERNAME": "[email protected]",
      "CONTEXTQA_PASSWORD": "yourpassword"
    }
  }
}

GitHub Actions CI

Store credentials as encrypted repository secrets in GitHub, then inject them as environment variables in the workflow:

- name: Run ContextQA via MCP
  env:
    CONTEXTQA_USERNAME: ${{ secrets.CONTEXTQA_USERNAME }}
    CONTEXTQA_PASSWORD: ${{ secrets.CONTEXTQA_PASSWORD }}
  run: |
    cd cqa-mcp
    uv run python -c "
    from app.contextqa_client import ContextQAClient
    import os
    client = ContextQAClient(
        username=os.environ['CONTEXTQA_USERNAME'],
        password=os.environ['CONTEXTQA_PASSWORD']
    )
    # ... tool calls
    "

Custom Agent (Python SDK)

When building a custom agent that calls the MCP server programmatically:

import os
import httpx

# Option A: Use the MCP HTTP endpoint directly
response = httpx.post(
    "http://localhost:8080/mcp",
    json={
        "jsonrpc": "2.0",
        "method": "tools/call",
        "params": {
            "name": "execute_test_case",
            "arguments": {"test_case_id": "1234"}
        },
        "id": 1
    }
)

# Option B: Pass credentials per-request via query param
response = httpx.post(
    "http://localhost:8080/mcp"
    f"?CONTEXTQA_USERNAME={os.environ['CQA_USER']}"
    f"&CONTEXTQA_PASSWORD={os.environ['CQA_PASS']}",
    json={...}
)

---

Security Best Practices

Do not hard-code credentials in source code. Always use environment variables, secrets management (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault), or the .env file pattern with the file excluded from version control.

Rotate passwords periodically. Since sessions are not cached, a password rotation takes effect on the next request. Update your environment variables and restart the server (or update the .env file and restart).

Use a dedicated service account. Create a ContextQA account specifically for CI/CD automation rather than using a personal account. This lets you revoke the service account independently and keeps audit logs clean.

Restrict network access for production servers. If deploying to Cloud Run or another cloud host, consider removing public access and routing requests through an authenticated proxy or VPN, unless the use case genuinely requires public accessibility.

Do not log credentials. The server is designed to never write credential values to logs. If you add custom logging to the server code, ensure you do not accidentally log the CONTEXTQA_PASSWORD value.

---

Next Steps

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

• Tool Reference — complete parameter documentation for all 67 tools

• Installation & Setup — if you have not yet started the server