# Connect a coding agent (MCP)

Source: https://docs.qualflare.com/docs/api/mcp · Last updated: 2026-10-27

Point Claude Code, Cursor or any MCP client at Qualflare to read suites, launches and defects. Creating test cases needs a token with Allow writes.

To connect an AI coding agent such as Claude Code or Cursor to Qualflare, add the MCP server `https://api.qualflare.com/mcp` to the agent with a project [access token](https://docs.qualflare.com/docs/reference/glossary#access-token); reads need a token creator with Viewer or higher, and writes need Editor and **Allow writes**.

This is different from the [Claude Code plugin](https://docs.qualflare.com/docs/ai/claude-code), which drives the
`qf` CLI from a chat window. The MCP server is a live connection to your project's data,
and any MCP client can use it.

## Before you begin

You need:

* An MCP-capable client — Claude Code, Cursor, or anything else that supports MCP
* A Qualflare **access token** for the project you want to work on — see
  [Access Tokens](https://docs.qualflare.com/docs/api/access-tokens). If the agent should create or edit data,
  tick **Allow writes** when you create the token.

The token decides everything: which project the agent sees, and what it may do there.

The person who created the token needs (requires the Viewer role or higher in the project) for reading; creating or editing data needs (requires the Editor role or higher in the project) and a token created with **Allow writes**.

*Figure: An agent that creates or edits test cases needs a token created with Allow writes.*

## The connection details

|               |                                             |
| ------------- | ------------------------------------------- |
| **Endpoint**  | `https://api.qualflare.com/mcp`             |
| **Transport** | Streamable HTTP                             |
| **Header**    | `Authorization: Bearer <your access token>` |

The **Connect a coding agent** panel under the token list on **Project Settings** > **Access Tokens** shows the same settings, ready to copy.

*Figure: The Access Tokens page shows the same connection settings for Claude Code and for JSON-configured clients.*

## Claude Code

1. **Put the token in a shell variable.** In bash or zsh, run `read -rs QF_TOKEN`, paste the token and press Enter. Nothing is shown, and the token stays out of your shell history.

2. **Add the Qualflare server:**

   ```bash
   claude mcp add --transport http qualflare https://api.qualflare.com/mcp \
     --header "Authorization: Bearer $QF_TOKEN"
   ```

3. **Ask a question.** Try something like "which suites have the most failures this week?": Claude Code calls the Qualflare tools to answer.

Claude Code stores the header, token included, in its own MCP configuration: treat that file like the token.

## Cursor and other JSON-configured clients

Most clients take a JSON block like this (Cursor reads `~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "qualflare": {
      "url": "https://api.qualflare.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}
```

Client configuration differs — check your client's own MCP documentation for where the file
lives and what it calls each field. The endpoint and the header are the same either way.

> **Warning:** Your token is a credential. Keep it in your user-level config or an environment variable,
> never in a project file such as `.mcp.json` or `.cursor/mcp.json` that gets committed. Revoke
> a token you have pasted somewhere shared (or ask a Maintainer or Owner to).

## Verify the connection

Ask the agent to list your project's test suites. It calls `list_test_suites` and answers with your suites. If it reports no Qualflare tools or an error, see [Troubleshooting](https://docs.qualflare.com/docs/api/mcp#troubleshooting).

## What the agent can do

It sees your project through the same API the CLI uses — 17 read tools and 8 write tools.
See [MCP Server](https://docs.qualflare.com/docs/api/mcp-reference) for the full list.

**Reading:** [test suites](https://docs.qualflare.com/docs/test-management/test-suites) and [cases](https://docs.qualflare.com/docs/test-management/test-cases), steps, [launches](https://docs.qualflare.com/docs/runs/launches) and their results, [defects](https://docs.qualflare.com/docs/defects), [milestones](https://docs.qualflare.com/docs/test-management/milestones),
[test plans](https://docs.qualflare.com/docs/test-management/test-plans), and [failure clusters](https://docs.qualflare.com/docs/ai/failure-clusters). It can also analyze a suite's coverage, which counts toward
your plan's monthly **Coverage Analysis** quota (available on Starter, Core, Scale, Enterprise, Open Source).

**Writing:** create and update test cases, steps and defects, add up to 20 cases to a suite
in one call, and save a suite's coverage score. Nothing is deleted, and uploading results
stays a CLI job.

## Permissions

Two checks run on every request, over MCP and over the API alike:

* **The token's access.** Every token can read. Only a token created with **Allow writes**
  can create or update data, and you can't add it later. The **Access** column in
  **Project Settings** > **Access Tokens** shows which kind you have.
* **The [current project role](https://docs.qualflare.com/docs/administration/roles-permissions) of the person who created the token.** Reading needs
  **Viewer** or higher. Writing needs **Editor** or higher. If that role is lowered or
  removed, the token loses that access immediately.

*Figure: The Access column shows whether a token can change data.*

Tokens created before **Allow writes** existed kept write access.

For an agent that only reads, use a token without **Allow writes**. The agent reads data
other people wrote, such as case names and CI failure output, exactly as stored. Check what
it plans to write before you approve it.

## Troubleshooting

**`401` / "invalid or expired access token"** — the token is wrong, revoked, or expired.
Create a fresh one in **Project Settings** > **Access Tokens**.

**`403` / "no project access"** — the token is valid, but its creator's role is too low for
what the agent tried. Reading needs Viewer; creating or updating needs Editor.

**The client connects but lists no tools** — check the URL ends in `/mcp` and that the
`Authorization` header is actually being sent; some clients need headers nested under the
server entry, as shown above.

**A write is refused with "this access token is read-only"** — the token was created
without **Allow writes**. Create a new token with **Allow writes** ticked, update your client,
and revoke the old one (or ask a Maintainer or Owner to).

## Next steps

* [MCP server reference](https://docs.qualflare.com/docs/api/mcp-reference)
* [Access Tokens](https://docs.qualflare.com/docs/api/access-tokens)
* [Authenticate the CLI with the same token](https://docs.qualflare.com/docs/cli/authentication)
* [Upload results from CI](https://docs.qualflare.com/docs/cli/ci-cd)