Installation & Setup

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 is a Python application that you run locally or deploy to a cloud host. Once running, it exposes a single HTTP endpoint that any MCP-compatible client can connect to. Setup takes under 5 minutes for a local install.

---

Prerequisites

Before you begin, make sure you have the following:

• Python 3.9 or higher — check with python --version

• uv (recommended) or pip — uv is faster and handles virtual environments automatically

• A ContextQA account — sign up at contextqa.com if you do not have one

• Git — to clone the repository

To install uv if you do not have it:

curl -LsSf https://astral.sh/uv/install.sh | sh

---

Option 1: Local with uv (Recommended)

This is the fastest path to a working server. uv handles the virtual environment and all dependency installation automatically.

git clone https://github.com/indivatools/cqa-mcp.git
cd cqa-mcp
uv sync

Set your credentials as environment variables:

export [email protected]
export CONTEXTQA_PASSWORD=yourpassword

Start the server:

python -m app.fastmcp_server

You should see output similar to:

INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)

The server is now running at http://0.0.0.0:8080 and ready to accept MCP connections.

Persisting Credentials with a .env File

Instead of exporting environment variables each session, create a .env file in the project root:

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

The server loads this file automatically on startup via python-dotenv. Do not commit this file to version control — it is already in .gitignore.

---

Option 2: Docker

Use Docker if you prefer a containerized deployment or want to run the server without installing Python dependencies on your host machine.

git clone https://github.com/indivatools/cqa-mcp.git
cd cqa-mcp

Create the credentials file:

echo "[email protected]" > .env
echo "CONTEXTQA_PASSWORD=yourpassword" >> .env

Build and start the container:

docker-compose up -d

The server will start in the background and be available at http://localhost:8080.

To view logs:

docker-compose logs -f

To stop the server:

docker-compose down

Docker without docker-compose

If you prefer to run Docker directly without Compose:

docker build -t contextqa-mcp .
docker run -d \
  -p 8080:8080 \
  -e [email protected] \
  -e CONTEXTQA_PASSWORD=yourpassword \
  --name contextqa-mcp \
  contextqa-mcp

---

Option 3: Google Cloud Run

For production use cases where you want a publicly accessible, auto-scaling deployment, Cloud Run is an ideal host. It costs nothing when idle and scales to handle burst traffic automatically.

Prerequisites

• Google Cloud SDK installed and authenticated (gcloud auth login)

• A GCP project with Cloud Run API enabled

Deploy

git clone https://github.com/indivatools/cqa-mcp.git
cd cqa-mcp

gcloud run deploy contextqa-mcp \
  --source . \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars [email protected],CONTEXTQA_PASSWORD=yourpassword

Cloud Run builds the container image from source using Cloud Build, pushes it to Artifact Registry, and deploys it. The command returns a service URL like:

https://contextqa-mcp-abc123-uc.a.run.app

Use this URL when configuring your MCP client (see Authentication for Claude Desktop configuration with a remote URL).

Securing a Cloud Run Deployment

The --allow-unauthenticated flag makes the endpoint publicly reachable. For team or production deployments, consider:

1. Removing --allow-unauthenticated and using Google Cloud IAM for access control

2. Adding a secret manager reference instead of inline env vars:

gcloud run deploy contextqa-mcp \
  --source . \
  --platform managed \
  --region us-central1 \
  --set-secrets CONTEXTQA_USERNAME=contextqa-username:latest,CONTEXTQA_PASSWORD=contextqa-password:latest

---

Option 4: Any Python-Compatible Host

The server is a standard ASGI application built on FastAPI. It can run on any host that supports Python:

# Install dependencies
pip install -r requirements.txt  # or: uv sync

# Set credentials
export [email protected]
export CONTEXTQA_PASSWORD=yourpassword

# Run with uvicorn directly
uvicorn app.fastmcp_server:app --host 0.0.0.0 --port 8080

This works on AWS EC2, Azure App Service, Railway, Render, Fly.io, or any VPS.

---

Verifying the Installation

After starting the server by any method, verify it is running correctly:

curl http://localhost:8080/health

Expected response:

{
  "status": "healthy",
  "service": "contextqa-mcp",
  "version": "1.0.0"
}

If you receive a connection refused error, check that:

1. The server process started without errors (check the terminal or Docker logs)

2. You are using the correct port (default is 8080)

3. No firewall rule is blocking the port

Test an Actual Tool Call

To confirm tool execution works end to end, you can make a direct HTTP call:

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

The response should include a tools array containing all 67 tool definitions. If you see an authentication error instead, double-check that your CONTEXTQA_USERNAME and CONTEXTQA_PASSWORD values are correct.

---

Connecting to Claude Desktop

Once the server is running, add it to your Claude Desktop configuration. Open (or create) the Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

For a local uv-based install:

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

For a remote (Docker or Cloud Run) deployment:

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

Restart Claude Desktop after saving the config. You should see a hammer icon in the input bar indicating that MCP tools are available.

---

Connecting to Cursor

In Cursor, open Settings → MCP and add a new server entry:

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

---

Updating the Server

To pull the latest version:

cd cqa-mcp
git pull origin main
uv sync

If you are using Docker, rebuild the image:

docker-compose down
docker-compose build --no-cache
docker-compose up -d

---

Network Requirements

The MCP server makes outbound HTTPS requests to three ContextQA backend services. If you run the server in a restricted network environment (corporate firewall, VPC, VPN-only egress), ensure outbound TCP port 443 is allowed to all three hostnames:

Service	Hostname	Purpose
Main API	server.contextqa.com	Test cases, environments, data profiles, execution results
Execution Engine	gcpn1.contextqa.com	Test plan execution, mobile device farm
AI Services	web-finder.contextqa.com	Root cause analysis, self-healing suggestions, custom agents, knowledge bases

All traffic uses HTTPS (port 443). No inbound ports need to be opened on the MCP server host — connections to the MCP server come only from the AI client (Claude Desktop, Cursor, etc.) running on the same machine or a trusted host.

---

Troubleshooting

Problem	Likely Cause	Fix
ModuleNotFoundError on startup	Dependencies not installed	Run uv sync or pip install -r requirements.txt
Authentication failed on every tool call	Wrong credentials	Verify CONTEXTQA_USERNAME and CONTEXTQA_PASSWORD are set correctly
Port 8080 already in use	Another process on that port	Change the port: uvicorn app.fastmcp_server:app --port 8081
Connection refused from Claude Desktop	Server not running	Check the terminal for startup errors; restart the server
Tools not appearing in Claude	Config file syntax error	Validate the JSON in claude_desktop_config.json with a JSON linter
Cloud Run deployment fails	Dockerfile missing or build error	Check Cloud Build logs in the GCP console
AI tools fail but execution tools work	web-finder.contextqa.com blocked	Add web-finder.contextqa.com to your firewall allowlist
Test plans fail but test cases work	gcpn1.contextqa.com blocked	Add gcpn1.contextqa.com to your firewall allowlist

---

Next Steps

• Authentication — detailed guide to credential management and multi-environment setups

• Agent Integration Guide — how to structure AI agent workflows with these tools

• Tool Reference — full parameter documentation for all 67 tools