Skip to main content

​
Connect Qodex over MCP

Qodex provides a remote Model Context Protocol (MCP) server. Connect it to a coding agent to inspect Qodex projects, look up saved test coverage, start saved test runs, and triage findings without leaving the agent. The MCP endpoint is:
For a self-hosted or preview Qodex instance, use the same origin followed by /mcp, for example https://qodex.example.com/mcp.

​
Connect with Claude Code

In a terminal, add the Qodex MCP server:
You can also open Settings > MCP in Qodex and copy the command with your current Qodex origin already filled in. The first time Claude Code calls a Qodex tool, it opens a browser for Qodex sign-in. Complete the sign-in there; no API key is needed for this normal interactive path. After connecting, ask your agent to call whoami to confirm the connection, then list_projects to choose a project. If your Qodex account has one active project, project-scoped tools select it automatically. Otherwise, pass the projectId returned by list_projects to the tool you want to use.

​
Connect with Cursor

  1. Create or open Cursor’s MCP configuration file. Use ~/.cursor/mcp.json to make Qodex available in every workspace, or .cursor/mcp.json in a project for that project only.
  2. Add the Qodex server, then save the file:
  1. In Cursor, open Customize and then MCP. Find Qodex and select Connect. Complete the Qodex sign-in in the browser when Cursor opens it.
  2. In Cursor Agent, ask: Use the qodex whoami tool. A successful response confirms that the connection is ready.
For a self-hosted or preview instance, replace the URL with that instance’s origin followed by /mcp.

​
Connect another coding agent

In an MCP-capable client, add a remote HTTP MCP server with the endpoint above. Use the client’s browser OAuth sign-in flow on its first Qodex tool call. This is a remote Qodex service; you do not need to run a local Qodex MCP process.
Use the exact MCP setup flow documented by your client. The client must support remote HTTP MCP servers and browser-based OAuth to use the interactive sign-in path.

​
Use a personal key for CI or headless automation

Use a personal key when the MCP client cannot open a browser, such as a CI runner.
  1. In the relevant Qodex project, open Settings > MCP.
  2. Under Personal keys, enter a descriptive name such as ci-regression.
  3. Choose Read only or Full access, then select Create key.
  4. Copy the key immediately. Qodex displays it only once.
  5. Configure your MCP client to send the key as an Authorization: Bearer <key> header to the same /mcp endpoint.
Personal keys are bound to one Qodex project. A read-only key can use read tools; a full-access key can also start runs and update a finding’s status. The key can never gain more access than the Qodex member who created it. Treat a personal key as a secret: store it in your CI provider’s secret store, never commit it, and revoke it from Settings > MCP if it is exposed.

​
Available tools

Qodex does not return raw environment variables, bearer tokens, cookies, request bodies, response bodies, headers, or logs through MCP. Open the Qodex web app when you need to inspect protected evidence. Once connected, give your agent a bounded request such as:
The agent can use list_projects, list_findings, list_suites, run_suite, and get_run in that order.

​
Troubleshooting

Run tests

Learn how saved scenarios and suites execute in Qodex.

Findings

Understand the findings that agents can inspect and triage.

Integrations

See every supported connection.