aspect mcp - Aspect Build

aspect mcp runs a Model Context Protocol (MCP) server that gives an AI agent read-only access to your build and test results: builds, their logs, the targets they built and tested, and statistics across builds. An agent can then work out why a build failed, find when a test started flaking or compare two runs by calling tools, without anyone pasting logs into the chat. The data comes from the build results REST API, on Aspect Cloud or on an Aspect Enterprise deployment running Aspect Workflows 6.0.30 or later with the API enabled.

aspect mcp                          # serve the default deployment
aspect mcp --deployment acme-corp   # serve one configured deployment

You don’t run it yourself. An AI tool launches aspect mcp and speaks MCP on its stdin and stdout; Connect an AI assistant to build results has the setup for Claude Code, Claude Desktop, Codex, Cursor and VS Code.

Flags

Flag	What it does
`--deployment <name>`	The configured deployment to serve, as listed by `aspect auth status`. Defaults to the default deployment. To serve several, register one server entry per deployment, each with its own `--deployment`.

How it behaves

Stdout carries the protocol. The server writes its banner and every diagnostic to stderr, so run in a terminal it prints a banner and waits for a client. Your AI tool’s MCP server log shows those diagnostics.
It uses your stored login. Each tool call authenticates with the credential aspect auth login stored for the deployment and refreshes it as needed, so a long agent session keeps working. There’s no URL or token in the server’s configuration.
It answers with the fix. When you aren’t logged in, or the deployment doesn’t serve the API, the tool call returns an error naming the command to run or the requirement to meet. The server checks again on the next call, so tools start working once the API is enabled, without restarting the client.
It only reads. No tool starts, cancels or changes a build.

Tools

Tool	What it reads
`list_invocations`	Builds, newest first; filterable by status, Bazel command, repository, or a Bazel-printed invocation UUID
`get_invocation`	One build in full: header, status, timings, VCS info, and links to its sub-resources
`get_invocation_configurations`	The build configurations present in one build; their ids feed `list_target_artifacts`
`get_invocation_metadata`	The user- and CI-supplied metadata key/values recorded on one build
`get_invocation_metrics`	One build’s performance metrics: action counts, cache hit rates, critical path, network and memory figures
`get_build_log`	One zero-indexed page of a build’s log
`tail_build_log`	The last page of a build’s log, usually where the failure is
`list_invocation_targets`	The targets one build built or tested, with per-target status; filterable to tests
`get_target_summary`	Aggregate counts of one build’s targets by outcome
`get_target`	One target’s detail within one build: kind, per-configuration results, and test detail
`list_target_artifacts`	The output artifacts one target produced in one build, for one configuration. Reads an endpoint Aspect Workflows 6.0.33 doesn’t serve yet, so it returns `404` there
`list_target_invocations`	The builds that built one target over a lookback window
`get_target_stats`	Cross-invocation statistics: build counts, failure and flake rates, durations
`get_action_history`	Execution-log history for an action-owner label, with full-window counts, timing percentiles, and optional daily buckets

Builds are addressed by the id these tools return, not by the invocation ID Bazel printed. The server tells the agent to resolve one to the other with list_invocations, so you can hand it a UUID from a CI log directly. Addressing a build explains why the two differ.

​Flags

​How it behaves

​Tools

Flags

How it behaves

Tools