# MCP server reference Source: https://docs.qualflare.com/docs/api/mcp-reference · Last updated: 2026-10-27 Reference for the Qualflare MCP server: endpoint, authentication, permissions, and all 17 read and 8 write tools an AI coding agent can call. 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](https://docs.qualflare.com/docs/reference/glossary#access-token) belongs to, with the same permissions as the qf CLI. For setup, see [Connect a coding agent](https://docs.qualflare.com/docs/api/mcp). | | | | ------------------ | ------------------------------------------------------------------------------------------------------------ | | **Endpoint** | `https://api.qualflare.com/mcp` | | **Transport** | Streamable HTTP, stateless | | **Authentication** | `Authorization: Bearer ` | | **Project** | Chosen by the token — no project argument exists on any tool | | **Read tools** | A token whose creator has (requires the Viewer role or higher in the project) | | **Write tools** | A token created with **Allow writes**, whose creator has (requires the Editor role or higher in the project) | | **Plans** | Every plan ([Plans and limits](https://docs.qualflare.com/docs/administration/plans#features-by-plan)) | ## 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](https://docs.qualflare.com/docs/administration/roles-permissions) of the person who created it. | Action | Requires | | -------------- | ------------------------------------------------------------------------------------------------------------------ | | Any read tool | (requires the Viewer role or higher in the project) (the token's creator) | | Any write tool | Token created with **Allow writes**, and (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: ```text 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](https://docs.qualflare.com/docs/test-management/test-suites), [test cases](https://docs.qualflare.com/docs/test-management/test-cases) and their steps, [launches](https://docs.qualflare.com/docs/runs/launches), [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). The qf CLI reads the same data with commands such as [`qf suites list`](https://docs.qualflare.com/docs/cli/read-commands#suites) and [`qf launches list`](https://docs.qualflare.com/docs/cli/read-commands#launches). | 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 (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](https://docs.qualflare.com/docs/reference/glossary#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](https://docs.qualflare.com/docs/administration/plans#limits), 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. > **Warning:** 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` / "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](https://docs.qualflare.com/docs/api/mcp-reference#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](https://docs.qualflare.com/docs/api/mcp#troubleshooting). ## Related * **Guides:** [Connect a coding agent (MCP)](https://docs.qualflare.com/docs/api/mcp) · [Claude Code plugin](https://docs.qualflare.com/docs/ai/claude-code) * **Reference:** [Access Tokens](https://docs.qualflare.com/docs/api/access-tokens) · [Roles](https://docs.qualflare.com/docs/administration/roles-permissions) · [Plans and limits](https://docs.qualflare.com/docs/administration/plans#limits) * **CLI/API:** [qf login and identifiers](https://docs.qualflare.com/docs/cli/authentication)