> ## Documentation Index
> Fetch the complete documentation index at: https://qodex.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

> Connect Qodex to a coding agent over MCP so it can inspect projects, run saved tests, triage findings, and ask about your code.

# 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:

```text theme={null}
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:

```bash theme={null}
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

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:

```json theme={null}
{
  "mcpServers": {
    "qodex": {
      "url": "https://agents.qodex.ai/mcp"
    }
  }
}
```

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

> [!TIP]
>
> 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 pipeline`.
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.

## 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](#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`:

```text theme={null}
You: Who calls chargeCard?
```

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

```json theme={null}
{
  "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
}
```

```text theme={null}
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:

```text theme={null}
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. |

## Related

> [card] [Run tests](https://qodex.ai/docs/run-tests.md)
>
> Learn how saved scenarios and suites execute in Qodex.

> [card] [Findings](https://qodex.ai/docs/findings.md)
>
> Understand the findings that agents can inspect and triage.

> [card] [Integrations](https://qodex.ai/docs/integrations.md)
>
> See every supported connection.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.