> ## Documentation Index > Fetch the complete documentation index at: https://site.aspect.build/llms.txt > Use this file to discover all available pages before exploring further. # Connect an AI assistant to build results with MCP > Point Claude Code, Claude Desktop, Codex, Cursor, or VS Code at the Aspect CLI's MCP server so your AI assistant can read build and test results from your Aspect Workflows deployment. The Aspect CLI ships a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server over the [build results REST API](/docs/aspect-workflows/platform/guides/build-results-api). Running `aspect mcp` exposes read-only build and test results from your Aspect Workflows deployment to any MCP-capable AI tool, such as Claude Code, Claude Desktop, Codex, and Cursor. Use it to work out why last night's build failed, find when a test started flaking, compare cache hit rates between two runs, or pull the tail of a build log into a fix, without pasting logs into the chat. ## Where it's available The MCP server reads the [REST API](/docs/aspect-workflows/platform/guides/build-results-api#where-its-available), which is available on [Aspect Cloud](/docs/aspect-workflows/cloud/overview) and on [Aspect Enterprise](/docs/aspect-workflows/enterprise/overview) deployments running Aspect Workflows 6.0.30 or later. On Aspect Enterprise the API is off by default, and until it's on, every tool call answers with that requirement instead of data. ## Prerequisites * **Aspect CLI 2026.39.10 or later.** Check with `aspect --version`. * **An Aspect Cloud account, or an Aspect Enterprise deployment running Aspect Workflows 6.0.30 or later with the API enabled** (see [Where it's available](#where-its-available)). * **If the deployment uses your own identity provider**, one identity provider application covering both the remote cluster and the Build Results UI. See [the REST API prerequisites](/docs/aspect-workflows/platform/guides/build-results-api#if-the-deployment-uses-your-own-identity-provider) for what to register, including the two-application case. * **An MCP-capable AI tool.** Setup for the common ones is below. ## Set up authentication One command, once per developer. There is no URL and no token in the MCP configuration itself: the server targets your default deployment and authenticates with the stored credential. ```bash theme={null} # Aspect Cloud: log in. Aspect Cloud is the CLI's default deployment. aspect auth login # Aspect Enterprise: record the deployment, make it the default, and log in. # This reads the deployment's own discovery document and opens a browser. aspect auth configure --default remote. ``` If you've already configured the deployment for the remote cache without `--default`, run `aspect auth use ` instead, or pin it in the client entry with `--deployment` (see [Serving several deployments](#serving-several-deployments)). `aspect auth status` lists the configured deployments and which one is the default. The credential is stored in your OS credential store (the macOS Keychain, or the Linux kernel keyring) and refreshed automatically for the life of an MCP session, so you don't repeat this per chat. ## Connect from common clients Each client launches `aspect mcp` itself and speaks MCP over that process's stdin and stdout. You don't run the server in a terminal. See [Troubleshooting](#troubleshooting) if you try and nothing appears to happen. GUI clients (Claude Desktop, Cursor, VS Code) start the server without your shell profile, so aspect may not be on their PATH. If a client reports that the server failed to start, replace "aspect" with the absolute path from which aspect. ### Claude Code Run once from your repository root: ```shell theme={null} claude mcp add --scope project aspect -- aspect mcp ``` That writes the entry into `.mcp.json` at the repo root, so everyone working in the repository picks it up: ```json theme={null} { "mcpServers": { "aspect": { "command": "aspect", "args": ["mcp"] } } } ``` Drop `--scope project` to add the server for yourself only. Verify with: ```shell theme={null} claude mcp list ``` ### Claude Desktop 1. Open **Settings → Developer → Edit Config**. This opens `claude_desktop_config.json` (`~/Library/Application Support/Claude/` on macOS, `%APPDATA%\Claude\` on Windows). 2. Add the server: ```json theme={null} { "mcpServers": { "aspect": { "command": "aspect", "args": ["mcp"] } } } ``` 3. Restart Claude Desktop. The Aspect tools are then available in a new chat. ### Codex CLI Add the server to `~/.codex/config.toml`: ```toml theme={null} [mcp_servers.aspect] command = "aspect" args = ["mcp"] ``` Then start a Codex session and ask *"What tools do you have available?"* The `aspect` server should be listed. ### Cursor 1. Open the command palette with `Cmd+Shift+P` (macOS) or `Ctrl+Shift+P` (Windows/Linux). 2. Run **Open MCP settings**. 3. Click **Add custom MCP** and add the following to `mcp.json`: ```json theme={null} { "mcpServers": { "aspect": { "command": "aspect", "args": ["mcp"] } } } ``` Use `.cursor/mcp.json` in the repository to scope the server to one project, or `~/.cursor/mcp.json` to make it available everywhere. ### VS Code Create `.vscode/mcp.json` in your workspace with: ```json theme={null} { "servers": { "aspect": { "type": "stdio", "command": "aspect", "args": ["mcp"] } } } ``` See the [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for details on scope and permissions. ## Serving several deployments With no arguments the server targets your default configured deployment. Pin a specific one by adding `--deployment` to the `args`: ```json theme={null} { "mcpServers": { "aspect-staging": { "command": "aspect", "args": ["mcp", "--deployment", "staging"] }, "aspect-prod": { "command": "aspect", "args": ["mcp", "--deployment", "prod"] } } } ``` Register one entry per deployment, each with its own `--deployment` and a distinct entry name. The name is how you and the assistant tell them apart. Deployment names come from `aspect auth status`. ## What the assistant can do with it Every tool is read-only. None starts, cancels, or modifies a build. [`aspect mcp`](/docs/cli/tasks/mcp#tools) lists the tools and what each one reads. ## Compare an action before and after a change Ask the assistant: "Compare `//web:bundle` on `main` in `my-repository` between September 1–7 and September 8–14. Exclude fully cached records and show daily execution-time trends." The assistant can call `get_action_history` for each window with `label`, RFC 3339 `start` and `end`, `repo`, `branch`, `cache: "miss"`, and `daily: true`. Each window may span at most 31 days. The tool also accepts `limit` and `offset` to page through individual invocation/label records; the summary and daily buckets always cover the whole filtered window. Timing percentiles measure **per-build totals for the label**, which may combine several spawns; they are not individual-spawn percentiles. See [Action performance history](/docs/aspect-workflows/platform/guides/build-results-api#action-performance-history) for cache-filter semantics, counts, and retention limitations. This tool requires Aspect CLI 2026.39.10 or later and Aspect Workflows 6.0.33 or later. Queries may wait up to five seconds for capacity. If the service stays busy, the query returns `503`: wait for the `Retry-After` interval before retrying. If the tool is absent, update the CLI and restart the MCP client. If it returns `404`, the deployment is older than 6.0.33. ## Troubleshooting The tools answer with the fix instead of a transport error, so the message you see in the assistant usually names the command to run. * **The tools don't appear after adding the server.** Restart the AI client. Most clients only load MCP servers at startup. * **"The deployment '…' does not expose the REST API the MCP server needs."** The deployment is older than Workflows 6.0.30, or the API isn't enabled. Ask your Workflows operator to enable it (see [Where it's available](/docs/aspect-workflows/platform/guides/build-results-api#where-its-available)). The server re-checks on every call, so the tools start working as soon as the flag lands, with no client restart. * **"Not logged in to the Aspect Workflows deployment '…'."** No stored credential for that deployment. Run the `aspect auth login` command the message names, then retry. An expired session reports the same command. * **"the credential was not accepted; run `aspect auth login …`"** on a call that used to work. The gateway rejected the token. Log in again. The server has already dropped the cached bearer, so the next call re-reads the credential store. * **The client reports that the server failed to start**, or the log shows `aspect: command not found`. A GUI client doesn't inherit your shell's `PATH`. Use the absolute path from `which aspect` as the `command`. * **"deployment '…' does not advertise a build-results URL."** The configured deployment has no Build Results UI, so there is no API host to read. Re-run `aspect auth configure --default ` against a deployment that serves the [Build Results UI](/docs/aspect-workflows/platform/features/webui). * **The assistant is reading the wrong deployment.** Without `--deployment` the server uses your default. Pin it explicitly: see [Serving several deployments](#serving-several-deployments). * **Running `aspect mcp` in a terminal prints one line and then hangs.** That is correct. The server owns stdout for the JSON-RPC stream and writes its banner and warnings to stderr; it waits for an MCP client to speak to it. Read those diagnostics in your client's MCP server logs. * **You want the setup steps without leaving the terminal.** `aspect mcp --help` carries the same recipe as this page.