Connect a coding agent (MCP)

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; reads need a token creator with Viewer or higher, and writes need Editor and Allow writes.

This is different from the Claude Code plugin, 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. 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 Viewer+ · project (requires the Viewer role or higher in the project) for reading; creating or editing data needs Editor+ · project (requires the Editor role or higher in the project) and a token created with Allow writes.

The connection details

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

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:

   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):

{
  "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.

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.

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 for the full list.

Reading: test suites and cases, steps, launches and their results, defects, milestones, test plans, and failure clusters. It can also analyze a suite's coverage, which counts toward your plan's monthly Coverage Analysis quota All plans (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 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.

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
• Access Tokens
• Authenticate the CLI with the same token
• Upload results from CI