MCP server reference
Reference for the Qualflare MCP server: endpoint, authentication, permissions, and all 17 read and 8 write tools an AI coding agent can call.
Last updated
The Qualflare MCP server at https://api.qualflare.com/mcp gives an AI coding agent 17 read tools and 8 write tools on the one project its access token belongs to, with the same permissions as the qf CLI. For setup, see Connect a coding agent.
| Endpoint | https://api.qualflare.com/mcp |
| Transport | Streamable HTTP, stateless |
| Authentication | Authorization: Bearer <access token> |
| Project | Chosen by the token — no project argument exists on any tool |
| Read tools | A token whose creator has Viewer+ · project (requires the Viewer role or higher in the project) |
| Write tools | A token created with Allow writes, whose creator has Editor+ · project (requires the Editor role or higher in the project) |
| Plans | Every plan (Plans and limits) |
Authentication and permissions
The MCP server takes the same access token as the CLI and the REST API, and applies the same rules. There is no MCP-specific key. What a token may do depends on whether it was created with Allow writes, and on the current project role of the person who created it.
| Action | Requires |
|---|---|
| Any read tool | Viewer+ · project (requires the Viewer role or higher in the project) (the token's creator) |
| Any write tool | Token created with Allow writes, and Editor+ · project (requires the Editor role or higher in the project) (the token's creator) |
The role is resolved per request, so a demotion takes effect immediately on tokens that person created. Allow writes is fixed when the token is created. Tokens created before it existed kept write access.
A write tool called with a token that lacks Allow writes returns this tool error:
this access token is read-only: it can read and upload test results, but changing cases, steps, defects or suites needs a token created with "Allow writes"No tool accepts a workspace, project or user ID. Those come from the token, which is what keeps one project's agent out of another's data.
Read tools
The read tools return the project's test suites, test cases and their steps, launches, defects, milestones, test plans and failure clusters. The qf CLI reads the same data with commands such as qf <identifier> suites list and qf <identifier> launches list.
| Tool | Returns |
|---|---|
list_test_suites | Test suites in the project, with paging and filters |
get_test_suite | One suite by its sequence number |
list_suite_cases | Test cases in a suite |
get_test_case | One test case |
list_case_steps | The steps of a test case |
list_launches | Test runs, newest first, with filters |
get_launch | One launch and its result counts |
list_defects | Defects, filterable by severity, status, environment and category |
get_defect | One defect |
list_milestones | Milestones |
get_milestone | One milestone |
list_test_plans | Test plans |
get_test_plan | One test plan |
list_test_plan_cases | The cases in a test plan |
list_failure_clusters | AI-grouped failure clusters |
get_failure_cluster | One cluster and its failures |
analyze_suite_coverage | A suite's coverage score, with a breakdown and recommendations. Saves nothing. Counts toward your plan's monthly Coverage Analysis quota All plans (available on Starter, Core, Scale, Enterprise, Open Source) |
Write tools
All eight are additive or partial updates. Nothing deletes.
| Tool | Does |
|---|---|
create_test_case | Adds a case to a suite, in draft state |
update_test_case | Changes a case's name, description, state or priority |
create_case_step | Adds a step to a case |
update_case_step | Changes a step's instruction, type or data |
create_defect | Files a defect |
update_defect | Changes a defect's fields, including its status |
bulk_create_cases | Adds 1 to 20 cases to a suite in one call, each with a title of 5 to 255 characters. Either all are created or none |
attach_coverage_score | Saves a 0–100 coverage score on a suite and records the change in the suite's coverage history |
Creating test cases counts against your plan's test-case limit, the same as creating them in
the app. When the limit is reached the tool fails and nothing is created. For
bulk_create_cases the limit covers the whole batch: if any case would go over it, none are
created.
A tool call is not idempotent. If an agent retries a create_* call that already succeeded,
you get a second record — worth knowing if you ask an agent to create many cases at once.
Notes for client authors
- Tool results are returned as structured content with a JSON text fallback, so clients on older MCP revisions can still read them.
- Two list tools —
list_case_stepsandlist_test_plan_cases— wrap their results as{"items": [...]}rather than returning a bare array, because not every client accepts a top-level array. - Asking for something that does not exist returns a tool error saying so, not an empty success.
- Tool names are stable, so an existing client will not break because a tool was renamed.
Errors
401/ "invalid or expired access token": the token is wrong, revoked or expired.403/ "no project access": the token is valid, but its creator's role is too low for the tool.- "this access token is read-only": a write tool was called with a token created without Allow writes. The full error is quoted in Authentication and permissions.
- A tool error naming what was not found: the record you asked for does not exist.
- A failed create at the test-case limit: the plan's test-case limit is reached, so the tool fails and nothing is created.
For how to fix the three token errors, see Troubleshooting.
Related
- Guides: Connect a coding agent (MCP) · Claude Code plugin
- Reference: Access Tokens · Roles · Plans and limits
- CLI/API: qf login and identifiers
Connect a coding agent (MCP)
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.
Administration
Administer a Qualflare workspace, from users, roles and projects to single sign-on, SCIM, audit logs, plans and limits, and your own account security.