# 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](/mcp-server/authentication.md) 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                   |

***

## Related Documentation

Now that the MCP server is running, explore the platform features you can control through it:

* [AI Test Generation](/ai-features/ai-test-generation.md) — understand the 10 generation sources available via MCP tools
* [Running Tests](/execution/running-tests.md) — how test execution works in ContextQA
* [Environments](/execution/environments.md) — configure the environments your MCP-triggered tests run against
* [Failure Analysis](/reporting/failure-analysis.md) — interpret the results returned by MCP analysis tools
* [GitHub Actions](/integrations/github-actions.md) — combine MCP with CI/CD for automated test pipelines
* [ContextQA for SDETs](/documentation-by-role/by-role/for-sdets.md) — role guide with MCP workflow patterns and architecture examples

***

## Next Steps

* [Authentication](/mcp-server/authentication.md) — detailed guide to credential management and multi-environment setups
* [Agent Integration Guide](/mcp-server/agent-integration-guide.md) — how to structure AI agent workflows with these tools
* [Tool Reference](/mcp-server/tool-reference.md) — full parameter documentation for all 67 tools


---

# Agent Instructions: 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:

```
GET https://learning.contextqa.com/mcp-server/installation-and-setup.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.