MCP server reference
Reference for the Qualflare MCP server: endpoint, authentication, permissions, and all 23 read and 13 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 23 read tools and 13 write tools on the one project you approved when you signed in, or its access token belongs to, with the same permissions as the qf CLI. MCP is the Model Context Protocol, an open protocol for connecting AI applications to external tools and data. For setup, see Connect a coding agent.
| Endpoint | https://api.qualflare.com/mcp |
| Transport | Streamable HTTP, stateless |
| Authentication | Sign-in (OAuth), or Authorization: Bearer <access token> |
| Project | Chosen when you approve the connection, or by the token. No project argument exists on any tool |
| Read tools | A connection whose person has Viewer+ · project (requires the Viewer role or higher in the project) |
| Write tools | A connection approved with Allow changes, or a token created with Allow writes, whose person has Editor+ · project (requires the Editor role or higher in the project) |
| Plans | Every plan, like the API (Plans and limits) |
| Rate limits | 5 requests per second per token or per sign-in connection, with bursts of up to 20, and 20 per second per IP address (Rate limits) |
Authentication and permissions
Most MCP clients connect with sign-in (OAuth): you approve one project and choose Allow changes or read-only, with no token to copy (Connect with sign-in). A client without sign-in sends a project access token instead, the same one the CLI and the REST API take. What a connection may do depends on whether it was approved with Allow changes (or a token created with Allow writes), and on the current project role of the person who approved it or created the token.
| Action | Requires |
|---|---|
| Any read tool | Viewer+ · project (requires the Viewer role or higher in the project) (the person who approved the app or created the token) |
| Any write tool | Allow changes (app) or Allow writes (token), and Editor+ · project (requires the Editor role or higher in the project) (the same person) |
The role is resolved per request, so a demotion takes effect immediately. Allow changes and Allow writes are fixed when the connection or token is created. Tokens created before Allow writes existed kept write access. An app is listed, and can be revoked, under Connected apps in Project Settings > Access Tokens (Manage and disconnect connected apps).
A write tool called by a read-only connection returns this tool error. For an app approved without Allow changes, revoke it and connect it again with Allow changes ticked:
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 connection, 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 |
|---|---|
testing_context | The next step of the browser-journey workflow for an intent: explore, generate, fix, rerun or report |
browser_capabilities | Whether Qualflare can run browser journeys for the project, and the journey tools. Starts no browser |
list_browser_targets | The project's browser targets: the Lovable apps journeys run against |
list_journeys | The project's browser journeys, optionally for one target, without steps |
get_journey | One journey with its current steps and version |
get_journey_run | A journey run's status, progress, step results and the launch it reported to |
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
Most are additive or partial updates. Only delete_journey deletes, and a journey's past runs and launches stay.
| 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 |
create_journey | Saves a browser journey on a target; runs nothing |
update_journey | Renames a journey or replaces its steps as a new version |
delete_journey | Deletes a journey; its runs, launches and test case stay |
run_journeys | Runs 1 to 20 of a target's journeys in the hosted browser and reports a launch |
cancel_journey_run | Cancels a journey run that has not finished |
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
401withinvalid or expired access token: the token is wrong, revoked or expired.403withno project access: the token or connection is valid, but its creator's (or, for a sign-in connection, its approver's) role is too low for the tool.- A sign-in connection that ended (revoked, unused for 30 days, or 90 days after approval) stops working: connect again.
this access token is read-only: a write tool was called with a token created without Allow writes, or by an app approved without Allow changes. 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.
429withcommon.rate_limited: the token or the IP address sent too many requests. Wait the seconds in theRetry-Afterheader, when it has one, and retry.
For how to fix these errors, see Troubleshooting. For every status the API returns, see Errors and status codes.
Related
- Guides: Connect a coding agent (MCP) · Claude Code plugin
- Reference: Access Tokens and Connected apps · Roles · Plans and limits
- CLI/API: qf login and identifiers
- Changelog: Connect Claude Code, Cursor and other coding agents to Qualflare over MCP
Connect a coding agent (MCP)
Connect Claude, Claude Code, Lovable or another MCP client to Qualflare by signing in and approving one project, or with a project access token.
Workspace admin guide
Run a Qualflare workspace as its Owner: a first-day checklist, the Owner-only pages, offboarding a member, deleting the workspace, and every admin page.