> ## 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, and triage findings.
# 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 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:
```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.
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 ` 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
| 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 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. |
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.
## 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
Learn how saved scenarios and suites execute in Qodex.
Understand the findings that agents can inspect and triage.
See every supported connection.