Skip to content
The docs are now organized by product area. Old links still work. Report a broken link

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.

Endpointhttps://api.qualflare.com/mcp
TransportStreamable HTTP, stateless
AuthenticationSign-in (OAuth), or Authorization: Bearer <access token>
ProjectChosen when you approve the connection, or by the token. No project argument exists on any tool
Read toolsA connection whose person has Viewer+ · project (requires the Viewer role or higher in the project)
Write toolsA 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)
PlansEvery plan, like the API (Plans and limits)
Rate limits5 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.

ActionRequires
Any read toolViewer+ · project (requires the Viewer role or higher in the project) (the person who approved the app or created the token)
Any write toolAllow 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.

ToolReturns
testing_contextThe next step of the browser-journey workflow for an intent: explore, generate, fix, rerun or report
browser_capabilitiesWhether Qualflare can run browser journeys for the project, and the journey tools. Starts no browser
list_browser_targetsThe project's browser targets: the Lovable apps journeys run against
list_journeysThe project's browser journeys, optionally for one target, without steps
get_journeyOne journey with its current steps and version
get_journey_runA journey run's status, progress, step results and the launch it reported to
list_test_suitesTest suites in the project, with paging and filters
get_test_suiteOne suite by its sequence number
list_suite_casesTest cases in a suite
get_test_caseOne test case
list_case_stepsThe steps of a test case
list_launchesTest runs, newest first, with filters
get_launchOne launch and its result counts
list_defectsDefects, filterable by severity, status, environment and category
get_defectOne defect
list_milestonesMilestones
get_milestoneOne milestone
list_test_plansTest plans
get_test_planOne test plan
list_test_plan_casesThe cases in a test plan
list_failure_clustersAI-grouped failure clusters
get_failure_clusterOne cluster and its failures
analyze_suite_coverageA 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.

ToolDoes
create_test_caseAdds a case to a suite, in draft state
update_test_caseChanges a case's name, description, state or priority
create_case_stepAdds a step to a case
update_case_stepChanges a step's instruction, type or data
create_defectFiles a defect
update_defectChanges a defect's fields, including its status
create_journeySaves a browser journey on a target; runs nothing
update_journeyRenames a journey or replaces its steps as a new version
delete_journeyDeletes a journey; its runs, launches and test case stay
run_journeysRuns 1 to 20 of a target's journeys in the hosted browser and reports a launch
cancel_journey_runCancels a journey run that has not finished
bulk_create_casesAdds 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_scoreSaves 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_steps and list_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 with invalid or expired access token: the token is wrong, revoked or expired.
  • 403 with no 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.
  • 429 with common.rate_limited: the token or the IP address sent too many requests. Wait the seconds in the Retry-After header, 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.