> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudeval.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP client setup
> Connect CloudEval's MCP server to Codex, Cursor, Claude Code, VS Code, or another MCP-compatible client.
Use CloudEval's MCP server when an agent should call CloudEval as a tool server instead of parsing CLI text output.
## Before you configure a client
Check the local MCP surface first:
```bash theme={null}
cloudeval mcp status --format json
cloudeval doctor --mcp --format json
```
Authenticate with one of these options:
* stored `cloudeval login` credentials
* stored `cloudeval login --headless` credentials for remote or SSH sessions
* `--machine` when your environment supports machine access
`mcp serve` uses stdin for MCP protocol messages, so run login before starting the MCP server.
## Choose a client
Client-specific steps also have stable in-page anchors for deeplinks from the app (`#codex`, `#cursor`, `#claude-code`, `#vs-code`).
## Codex
Generate the Codex setup guidance:
```bash theme={null}
cloudeval mcp setup codex --dry-run
```
A typical local registration uses the CloudEval stdio server:
```bash theme={null}
codex mcp add cloudeval -- cloudeval mcp serve
```
Use a focused toolset when Codex should only inspect part of the product:
```bash theme={null}
codex mcp add cloudeval-reports -- cloudeval mcp serve --toolset reports
```
## Cursor
Generate Cursor setup guidance:
```bash theme={null}
cloudeval mcp setup cursor --dry-run
```
Use the generated `mcpServers` entry in Cursor's MCP configuration surface.
Keep secrets in Cursor environment configuration or stored CloudEval login state, not inline command arguments.
## Claude Code
If your Claude Code environment accepts an `mcpServers` JSON entry, start with the generic output:
```bash theme={null}
cloudeval mcp setup generic --dry-run --format json
```
If your local CloudEval CLI supports a Claude-specific target for your installed Claude client, you can inspect that output too:
```bash theme={null}
cloudeval mcp setup claude --dry-run
```
Use the generated stdio command and keep authentication in stored login state or environment variables.
## VS Code
Generate VS Code MCP configuration for the current workspace:
```bash theme={null}
cloudeval mcp setup vscode --dry-run
```
By default this targets `.vscode/mcp.json` in the current directory. Use the generated stdio command in your VS Code MCP extension or built-in MCP configuration surface.
If your extension expects generic `mcpServers` JSON instead, you can still use:
```bash theme={null}
cloudeval mcp setup generic --dry-run --format json
```
The important part is that the server command runs:
```bash theme={null}
cloudeval mcp serve
```
`mcp setup --toolset` supports `all`, `readonly`, `projects`, `reports`, and `billing`.
Use `mcp serve --toolset graph` or `mcp serve --toolset validation` when the editor agent needs those narrower surfaces.
## Focus tool access
Use focused toolsets when the assistant should have a narrower CloudEval surface.
| Toolset | Use it for |
| ------------ | -------------------------------------------------------------------------- |
| `all` | Full CloudEval MCP surface |
| `readonly` | Read-only project, report, billing, and capability discovery |
| `projects` | Project lookup, creation handoff, project deeplinks, and project context |
| `reports` | Report runs, report downloads, report deeplinks, and latest report context |
| `billing` | Billing and credit inspection |
| `graph` | Project graph, timeline, diff, sync runs, and insight reads |
| `validation` | Template validation, parsing, and validation rule catalog reads |
Example:
```bash theme={null}
cloudeval mcp serve --toolset readonly
cloudeval mcp serve --toolset graph
cloudeval mcp serve --toolset validation
```
Agent Profile tools are available in the full and read-only MCP surfaces:
`agent_profiles_list`, `agent_profiles_get`, and `agent_profiles_run`. They use
the same canonical profile ids as the CLI: `architecture`, `cost`, `triage`,
and `remediation`.
The validation toolset exposes `template_validate`, `template_test`,
`template_parse`, `rules_categories`, `rules_search`, and `rules_get`.
`template_validate`, `template_test`, and `template_parse` all accept an
optional `parametersFile` argument. `template_validate` accepts `ruleId` for one
check or `ruleNames` for multiple check ids, `details` for frontend-style
per-check evidence, and `wait` when the client needs completed validation
results instead of only a submitted job. `template_test` accepts `includeTests`,
`skipTests`, `category`, `testGroups`, and `wait`. Use `waitTimeoutMs` with
`wait` for bounded automation runs.
When a validation call uses `wait`, MCP clients can include
`_meta.progressToken` in the `tools/call` params to receive
`notifications/progress` updates for queued, running, and completed states.
Completed progress messages include failing check/test details such as message,
recommendation, severity, and file/template or resource location when
available. If a completed backend result only has a worker-local temp file path,
CloudEval reports the submitted template filename instead.
The graph toolset exposes `projects_graph_get`, `projects_graph_timeline`,
`projects_graph_diff`, `projects_graph_insights`, and
`projects_graph_sync_runs`.
## Verify the integration
After configuring the client:
1. Restart the MCP client if it requires a restart.
2. Ask the client to list available CloudEval tools.
3. Run a low-risk command such as capability discovery or project listing.
4. Confirm the result uses the expected CloudEval profile, base URL, and auth mode.
## Next step
Use [Agent and automation rules](/reference/agent-and-automation-rules) for safety defaults, or [CLI command reference](/reference/cli-command-reference) for the MCP command surface.
## Before you configure a client
Check the local MCP surface first:
```bash theme={null}
cloudeval mcp status --format json
cloudeval doctor --mcp --format json
```
Authenticate with one of these options:
* stored `cloudeval login` credentials
* stored `cloudeval login --headless` credentials for remote or SSH sessions
* `--machine` when your environment supports machine access
`mcp serve` uses stdin for MCP protocol messages, so run login before starting the MCP server.
## Choose a client
Client-specific steps also have stable in-page anchors for deeplinks from the app (`#codex`, `#cursor`, `#claude-code`, `#vs-code`).
## Codex
Generate the Codex setup guidance:
```bash theme={null}
cloudeval mcp setup codex --dry-run
```
A typical local registration uses the CloudEval stdio server:
```bash theme={null}
codex mcp add cloudeval -- cloudeval mcp serve
```
Use a focused toolset when Codex should only inspect part of the product:
```bash theme={null}
codex mcp add cloudeval-reports -- cloudeval mcp serve --toolset reports
```
## Cursor
Generate Cursor setup guidance:
```bash theme={null}
cloudeval mcp setup cursor --dry-run
```
Use the generated `mcpServers` entry in Cursor's MCP configuration surface.
Keep secrets in Cursor environment configuration or stored CloudEval login state, not inline command arguments.
## Claude Code
If your Claude Code environment accepts an `mcpServers` JSON entry, start with the generic output:
```bash theme={null}
cloudeval mcp setup generic --dry-run --format json
```
If your local CloudEval CLI supports a Claude-specific target for your installed Claude client, you can inspect that output too:
```bash theme={null}
cloudeval mcp setup claude --dry-run
```
Use the generated stdio command and keep authentication in stored login state or environment variables.
## VS Code
Generate VS Code MCP configuration for the current workspace:
```bash theme={null}
cloudeval mcp setup vscode --dry-run
```
By default this targets `.vscode/mcp.json` in the current directory. Use the generated stdio command in your VS Code MCP extension or built-in MCP configuration surface.
If your extension expects generic `mcpServers` JSON instead, you can still use:
```bash theme={null}
cloudeval mcp setup generic --dry-run --format json
```
The important part is that the server command runs:
```bash theme={null}
cloudeval mcp serve
```
`mcp setup --toolset` supports `all`, `readonly`, `projects`, `reports`, and `billing`.
Use `mcp serve --toolset graph` or `mcp serve --toolset validation` when the editor agent needs those narrower surfaces.
## Focus tool access
Use focused toolsets when the assistant should have a narrower CloudEval surface.
| Toolset | Use it for |
| ------------ | -------------------------------------------------------------------------- |
| `all` | Full CloudEval MCP surface |
| `readonly` | Read-only project, report, billing, and capability discovery |
| `projects` | Project lookup, creation handoff, project deeplinks, and project context |
| `reports` | Report runs, report downloads, report deeplinks, and latest report context |
| `billing` | Billing and credit inspection |
| `graph` | Project graph, timeline, diff, sync runs, and insight reads |
| `validation` | Template validation, parsing, and validation rule catalog reads |
Example:
```bash theme={null}
cloudeval mcp serve --toolset readonly
cloudeval mcp serve --toolset graph
cloudeval mcp serve --toolset validation
```
Agent Profile tools are available in the full and read-only MCP surfaces:
`agent_profiles_list`, `agent_profiles_get`, and `agent_profiles_run`. They use
the same canonical profile ids as the CLI: `architecture`, `cost`, `triage`,
and `remediation`.
The validation toolset exposes `template_validate`, `template_test`,
`template_parse`, `rules_categories`, `rules_search`, and `rules_get`.
`template_validate`, `template_test`, and `template_parse` all accept an
optional `parametersFile` argument. `template_validate` accepts `ruleId` for one
check or `ruleNames` for multiple check ids, `details` for frontend-style
per-check evidence, and `wait` when the client needs completed validation
results instead of only a submitted job. `template_test` accepts `includeTests`,
`skipTests`, `category`, `testGroups`, and `wait`. Use `waitTimeoutMs` with
`wait` for bounded automation runs.
When a validation call uses `wait`, MCP clients can include
`_meta.progressToken` in the `tools/call` params to receive
`notifications/progress` updates for queued, running, and completed states.
Completed progress messages include failing check/test details such as message,
recommendation, severity, and file/template or resource location when
available. If a completed backend result only has a worker-local temp file path,
CloudEval reports the submitted template filename instead.
The graph toolset exposes `projects_graph_get`, `projects_graph_timeline`,
`projects_graph_diff`, `projects_graph_insights`, and
`projects_graph_sync_runs`.
## Verify the integration
After configuring the client:
1. Restart the MCP client if it requires a restart.
2. Ask the client to list available CloudEval tools.
3. Run a low-risk command such as capability discovery or project listing.
4. Confirm the result uses the expected CloudEval profile, base URL, and auth mode.
## Next step
Use [Agent and automation rules](/reference/agent-and-automation-rules) for safety defaults, or [CLI command reference](/reference/cli-command-reference) for the MCP command surface.