# Installation & Setup

{% hint style="info" %}
**Who is this for?** SDETs, developers, and DevOps engineers integrating ContextQA with AI coding assistants (Claude, Cursor) or CI/CD pipelines.
{% endhint %}

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](https://contextqa.com) if you do not have one
* **Git** — to clone the repository

To install uv if you do not have it:

```bash
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.

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

Set your credentials as environment variables:

```bash
export CONTEXTQA_USERNAME=your@email.com
export CONTEXTQA_PASSWORD=yourpassword
```

Start the server:

```bash
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:

```bash
# cqa-mcp/.env
CONTEXTQA_USERNAME=your@email.com
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.

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

Create the credentials file:

```bash
echo "CONTEXTQA_USERNAME=your@email.com" > .env
echo "CONTEXTQA_PASSWORD=yourpassword" >> .env
```

Build and start the container:

```bash
docker-compose up -d
```

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

To view logs:

```bash
docker-compose logs -f
```

To stop the server:

```bash
docker-compose down
```

### Docker without docker-compose

If you prefer to run Docker directly without Compose:

```bash
docker build -t contextqa-mcp .
docker run -d \
  -p 8080:8080 \
  -e CONTEXTQA_USERNAME=your@email.com \
  -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

```bash
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 CONTEXTQA_USERNAME=your@email.com,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](https://learning.contextqa.com/mcp-server/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:

```bash
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:

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

# Set credentials
export CONTEXTQA_USERNAME=your@email.com
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:

```bash
curl http://localhost:8080/health
```

Expected response:

```json
{
  "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:

```bash
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:

```json
{
  "mcpServers": {
    "contextqa": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/cqa-mcp", "run", "mcp-contextqa"],
      "env": {
        "CONTEXTQA_USERNAME": "your@email.com",
        "CONTEXTQA_PASSWORD": "yourpassword"
      }
    }
  }
}
```

For a remote (Docker or Cloud Run) deployment:

```json
{
  "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:

```json
{
  "contextqa": {
    "command": "uv",
    "args": ["--directory", "/absolute/path/to/cqa-mcp", "run", "mcp-contextqa"],
    "env": {
      "CONTEXTQA_USERNAME": "your@email.com",
      "CONTEXTQA_PASSWORD": "yourpassword"
    }
  }
}
```

***

## Updating the Server

To pull the latest version:

```bash
cd cqa-mcp
git pull origin main
uv sync
```

If you are using Docker, rebuild the image:

```bash
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](https://learning.contextqa.com/mcp-server/authentication) — detailed guide to credential management and multi-environment setups
* [Agent Integration Guide](https://learning.contextqa.com/mcp-server/agent-integration-guide) — how to structure AI agent workflows with these tools
* [Tool Reference](https://learning.contextqa.com/mcp-server/tool-reference) — full parameter documentation for all 67 tools