Connect an AI assistant to build results with MCP

The Aspect CLI ships a Model Context Protocol (MCP) server over the build results REST 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, which is available on Aspect Cloud and on Aspect Enterprise 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).
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 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.

# 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.<your-domain>

If you’ve already configured the deployment for the remote cache without --default, run aspect auth use <name> instead, or pin it in the client entry with --deployment (see 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 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:

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:

{
  "mcpServers": {
    "aspect": {
      "command": "aspect",
      "args": ["mcp"]
    }
  }
}

Drop --scope project to add the server for yourself only. Verify with:

claude mcp list

Claude Desktop

Open Settings → Developer → Edit Config. This opens claude_desktop_config.json (~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows).
Add the server:

{
  "mcpServers": {
    "aspect": {
      "command": "aspect",
      "args": ["mcp"]
    }
  }
}

Restart Claude Desktop. The Aspect tools are then available in a new chat.

Codex CLI

Add the server to ~/.codex/config.toml:

[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

Open the command palette with Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux).
Run Open MCP settings.
Click Add custom MCP and add the following to mcp.json:

{
  "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:

{
  "servers": {
    "aspect": {
      "type": "stdio",
      "command": "aspect",
      "args": ["mcp"]
    }
  }
}

See the VS Code MCP documentation 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:

{
  "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 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 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). 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 <remote-host> against a deployment that serves the Build Results UI.
The assistant is reading the wrong deployment. Without --deployment the server uses your default. Pin it explicitly: see 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.

​Where it’s available

​Prerequisites

​Set up authentication

​Connect from common clients

​Claude Code

​Claude Desktop

​Codex CLI

​Cursor

​VS Code

​Serving several deployments

​What the assistant can do with it

​Compare an action before and after a change

​Troubleshooting

Where it’s available

Prerequisites

Set up authentication

Connect from common clients

Claude Code

Claude Desktop

Codex CLI

Cursor

VS Code

Serving several deployments

What the assistant can do with it

Compare an action before and after a change

Troubleshooting