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:

https://agents.qodex.ai/mcp

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:

claude mcp add --transport http qodex https://agents.qodex.ai/mcp

You can also copy the command from Qodex with your current Qodex origin already filled in: open the account menu at the bottom of the left navigation, choose Settings, then open MCP. The Add the server and MCP endpoint fields each have a copy button. 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

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.
Add the Qodex server, then save the file:

{
  "mcpServers": {
    "qodex": {
      "url": "https://agents.qodex.ai/mcp"
    }
  }
}

In Cursor, open Customize and then MCP. Find Qodex and select Connect. Complete the Qodex sign-in in the browser when Cursor opens it.
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.

In the relevant Qodex project, open Settings > MCP.
Under Personal keys, enter a descriptive name such as CI pipeline.
Choose Read only or Full access, then select Create key.
Copy the key immediately. Qodex displays it only once.
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.

Revoke a personal key

Open Settings > MCP, find the key under Personal keys, click Revoke, then click Revoke again in the inline confirmation. The key stops authorizing headless MCP clients immediately; update or remove the corresponding CI secret at the same time.

Available tools

Area	Tools	What the agent can do
Connection	`whoami`, `list_projects`	Verify its Qodex identity and discover accessible projects.
Scenarios and suites	`list_scenarios`, `get_scenario`, `list_suites`, `get_suite`	Inspect saved coverage and its test groups.
Test runs	`run_scenario`, `run_suite`, `list_runs`, `get_run`	Start a saved scenario or suite, then inspect the asynchronous run result.
Findings	`list_findings`, `get_finding`, `finding_stats`, `set_finding_status`	Review product findings from testing and from code scans, and, with full access, triage their status.
Project context	`search_endpoints`, `search_app_behavior`, `list_environments`	Search the endpoint catalog and learned app behavior, and see safe environment metadata.
Code graph	`code_repos`, `code_overview`, `code_outline`, `code_search`, `code_symbol`, `code_callers`, `code_callees`, `code_path`, `code_impact`, `code_tests`	Ask how the code of a connected repo fits together. See Code graph.

list_findings returns findings from testing and from code scans. Filter with source set to testing or code_scan; leave it out to get both. get_finding includes a code scan finding’s file location. Full-app security scan findings are not included. A finding in needs_review is a candidate an Autopilot run raised that still waits for a person to decide; it cannot be triaged through set_finding_status. 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.

Code graph

The code graph tools answer questions about the code of a repository connected to your Qodex project, such as “what does the billing module import” or “who calls chargeCard”. A code graph is a map of the repository’s files, symbols (functions, classes and methods) and how they connect: calls, imports and inheritance. Qodex builds it on its own servers, so nothing runs on your machine. Each call, import or inheritance link that code_callers, code_callees and code_path return comes with a tier (certain, likely or possible) and the evidence for it.

Tool	What it answers	Inputs
`code_repos`	Every connected repository with its graph state, build time, commit, file and symbol counts, and languages. Call it first.	None
`code_overview`	The folders and files under a folder, with file and symbol counts, the packages, and routes as entry points.	`repo`, `folder`
`code_outline`	The symbols a file or folder defines, with kind and line span.	`repo`, `path`
`code_search`	Definitions whose name matches a query, best match first.	`repo`, `query`, `kind`
`code_symbol`	One symbol: where it is defined, what it calls, and what its file imports.	`repo`, `name`, or `file` and `line`
`code_callers`	Who calls a function, method or class, up to three hops back.	`repo`, `symbol`, `file`, `depth`
`code_callees`	What a function or method calls, up to three hops out.	`repo`, `symbol`, `file`, `depth`
`code_path`	The shortest path between two files or two symbols.	`repo`, `from`, `to`, `edges`
`code_impact`	What a change to some files or symbols reaches, including the routes and tests that reach it.	`repo`, `files`, `symbols`
`code_tests`	The tests that reach a file, a symbol or a route. Where no framework was recognized, test files that may reach it come back marked `lead: true`, not as proof of coverage. An empty list is not proof that no test reaches the code: tests are marked only inside the frameworks Qodex recognizes today.	`repo`, `path`, `route`

All ten tools are read only, so a read-only personal key can use them.

Repository name. Pass repo as org/name, the name code_repos lists. When your project connects one repository once per folder, the name is org/name:<folder>. With one connected repository you can leave repo out.
Freshness. Qodex rebuilds the graph on every push and once a day. A push or merge to the default branch queues a rebuild in the background, and pushes close together share one rebuild. A daily check rebuilds any graph that is missing, failed or a day old. Refreshing the repository in Qodex rebuilds it too. Every answer names the commit and build time it comes from, so you can tell when it is behind.
Languages. TypeScript, TSX, JavaScript, Python, Go and Ruby. Framework support varies: routes are recognized for Express, Next.js, Django, FastAPI, Rails and Go net/http, and React components and their tests are recognized too.
Location only. The tools return where code is and how it connects, never its source text. Open the file in your editor to read it.
Long lists. A list holds at most 200 items, says when it was cut, and gives the total when it is known.
Not ready yet. When a graph is still building or its last build failed, the tools say so in one sentence. Project admins also see the build error.

Example

In Claude Code, connected to a project that links the repository northfield-school/fees-portal:

You: Who calls chargeCard?

Claude Code calls code_callers with {"symbol": "chargeCard"} and gets back (trimmed):

{
  "repo": "northfield-school/fees-portal",
  "commitSha": "4f2a9c1",
  "builtAt": "2026-10-22T08:14:03.000Z",
  "symbol": { "name": "chargeCard", "kind": "function", "file": "src/billing/charge.ts", "line": 18 },
  "callers": [
    { "name": "payTermFees", "kind": "function", "file": "src/fees/pay.ts", "line": 31, "depth": 1, "relation": "calls", "site": "src/fees/pay.ts:44", "tier": "certain", "evidence": "import" },
    { "name": "retryFailedPayments", "kind": "function", "file": "src/jobs/retry.ts", "line": 9, "depth": 1, "relation": "calls", "site": "src/jobs/retry.ts:22", "tier": "certain", "evidence": "import" }
  ],
  "unknown": { "floor": false, "reasons": [] },
  "truncated": false,
  "total": 2
}

Claude Code: Two functions call chargeCard: payTermFees in src/fees/pay.ts (line 44) and retryFailedPayments in src/jobs/retry.ts (line 22). Both calls are certain.

When unknown.floor is true, some calls in the repository could not be resolved, so the list is a minimum, not the whole answer.

Recommended first prompt

Once connected, give your agent a bounded request such as:

Use Qodex to list my projects, select the Payments project, show open critical and high findings, then run the smoke suite in staging and summarize the result.

The agent can use list_projects, list_findings, list_suites, run_suite, and get_run in that order.

Troubleshooting

Symptom	What to check
The client cannot connect	Confirm the server URL ends in `/mcp` and the client is configured for remote HTTP MCP.
Sign-in repeats or fails	Complete the browser sign-in in the same client session, then retry the first tool call.
The agent asks which project to use	This is expected when your Qodex account has multiple active projects. Have it call `list_projects` and pass a `projectId`.
A headless job receives `unauthorized`	Ensure the client sends the personal key in an `Authorization: Bearer` header and that the key has not been revoked.
A run or triage call is forbidden	Create a Full access personal key or use an account with at least member access to the project.

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.

Get started

Concepts

PR review

API testing

UI testing

Security testing

Load testing

Run tests

Autopilot

Findings

Memory

Skills

Integrations

Self-hosted

Account

MCP

Connect Qodex over MCP

Connect with Claude Code

Connect with Cursor

Connect another coding agent

Use a personal key for CI or headless automation

Revoke a personal key

Available tools

Code graph

Example

Recommended first prompt

Troubleshooting

Run tests

Findings

Integrations

​Connect Qodex over MCP

​Connect with Claude Code

​Connect with Cursor

​Connect another coding agent

​Use a personal key for CI or headless automation

​Revoke a personal key

​Available tools

​Code graph

​Example

​Recommended first prompt

​Troubleshooting

​Related

Run tests

Findings

Integrations

Connect Qodex over MCP

Connect with Claude Code

Connect with Cursor

Connect another coding agent

Use a personal key for CI or headless automation

Revoke a personal key

Available tools

Code graph

Example

Recommended first prompt

Troubleshooting

Related