Verify the configured Depot token and report which organizations and projects it can actually see.

Call this first whenever another Depot tool returns an empty list or a permission error. Depot's most common confusing failure is a token that spans several organizations with none selected: requests then resolve against the wrong organization and return empty results rather than an error. This tool says plainly whether that is happening and what to set.

Also reports whether write tools are enabled (DEPOT_MCP_ALLOW_WRITES) and which mutating tools are registered, whether the destructive gate is open (DEPOT_MCP_ALLOW_DESTRUCTIVE, which adds depot_delete_project only when writes are on too), and whether the beta sandbox and registry tools are registered (DEPOT_MCP_ENABLE_BETA). With the write flag unset no mutating tool exists, and nothing here can retry, cancel, rerun, or delete anything.

Never returns the token or any part of it.

Explain why a Depot CI run, workflow, job, or attempt failed.

Reach for this first whenever someone asks why CI failed, what broke the build, or to fix a failing job. It calls Depot's server-side failure analysis, which clusters every failure in the target by root cause and returns, for each cluster: the error message, an AI-written diagnosis, a suggested fix, and the exact log lines that are the evidence.

Prefer this over depot_get_ci_logs. Depot bounds this response server-side, so it costs far less context than raw logs, and it already works out which job is the real root cause rather than a downstream casualty. Use depot_get_ci_logs afterwards only if you need more detail on a specific attempt.

Pass whichever identifier you have in "id" — a run, workflow, job, or attempt ID. This server works out which kind it is; set "targetType" only when you already know it and want to skip that step.

How to read the returned "state":

• "focused_failure": one clear culprit. Read representativeAttempts.

• "grouped_failures": several distinct root causes, clustered by fingerprint. Read failureGroups.

• "over_limit": too many failures to analyse at this level. narrowerTargets gives the IDs to call this tool again with.

• "empty": Depot found no failure evidence. The target may still be running, may have succeeded, or may be old enough that its logs have aged out.

Diagnoses and suggested fixes are generated by Depot's AI and can be wrong — treat them as a lead to verify, not a fact. Read-only: this never retries, cancels, or triggers anything.

List recent Depot CI runs, newest first, optionally filtered by status, repository, commit, trigger, or pull request.

Use this to find the run someone is talking about — "my last failed build", "did main go green", "what ran for PR 412" — and then pass the returned runId to depot_diagnose_ci_failure or depot_get_ci_run.

The fastest path to diagnosing a recent breakage is status=["failed"] with limit=1, then depot_diagnose_ci_failure on the runId that comes back.

Returns identity, status and timing only. It does not return logs or failure detail; use depot_diagnose_ci_failure for that.

Show one Depot CI run as its workflow -> job -> attempt tree, with the status of every node and the ids needed to drill in.

Use this to see the shape of a run: which jobs exist, which failed, and which attempt ids to pass to depot_get_ci_logs or depot_get_ci_metrics. Set failedOnly=true to cut a large matrix down to just the broken jobs.

This does not explain failures — it only reports structure and status. For root cause, call depot_diagnose_ci_failure with the same run id.

Show one Depot CI job: its status, conclusion, recorded error, runner labels, timing, and every attempt with the attempt and sandbox ids needed to drill in.

Use this when you already have a jobId (from depot_get_ci_run or a diagnosis) and want to know what happened to that job across retries: which attempt is current, whether earlier attempts failed the same way, how long each took, and where each ran. It fills the gap between the run tree and the raw logs.

It does not explain the failure and does not return logs. For root cause, call depot_diagnose_ci_failure with the same jobId; for a single attempt's record, depot_get_ci_attempt; for the whole run, depot_get_ci_run.

Show one attempt of a Depot CI job: its status, conclusion, recorded error, sandbox and session ids, timing, and whether it is the job's current attempt, with the parent job, workflow, and run for context.

Use this when you hold an attemptId (from depot_get_ci_run, depot_get_ci_job, or a diagnosis) and need that attempt's own record, for example to confirm which sandbox a retry ran in or how long it took before failing.

It does not explain the failure and does not return logs. For root cause, call depot_diagnose_ci_failure with the same id and targetType "attempt"; for raw output, depot_get_ci_logs; to compare all attempts of the job, depot_get_ci_job.

List recent Depot CI workflows, newest first, with each one's status and job counts, optionally filtered by workflow name, status, repository, commit, trigger, or pull request.

Use this when the question is about a named workflow rather than a whole run: "is the deploy workflow green", "which CI workflows failed today", "how many jobs failed in the release workflow". A run groups every workflow a push triggered; this lists the workflows themselves, each with its parent runId.

Returns identity, status, and counts only. It does not return jobs or failure detail: pass a workflowId to depot_get_ci_workflow for its jobs and rerun history, or to depot_diagnose_ci_failure with targetType "workflow" for root cause.

Show one Depot CI workflow: its status and timing, its parent run, its execution history (every rerun or retry, oldest first), and its job -> attempt tree with the ids needed to drill in.

Use this when you have a workflowId (from depot_list_ci_workflows, depot_get_ci_run, or a diagnosis) and want to see how the workflow has been rerun and which of its jobs and attempts failed. It is the workflow-level counterpart of depot_get_ci_run.

It does not explain failures or return logs. For root cause, call depot_diagnose_ci_failure with the same id and targetType "workflow"; for one job across its attempts, depot_get_ci_job; for a whole run with several workflows, depot_get_ci_run.

Wait, for a bounded time, until a Depot CI run, one workflow in it, or one job reaches a terminal state, then report the outcome and which nodes changed state while waiting.

Use this after a push or a rerun when the next step depends on the result: "wait for the run to finish, then diagnose it if it failed". Pass runId to watch a whole run. Pass workflowId to watch one workflow: this is what to do after depot_rerun_ci_workflow or depot_retry_ci_failed_jobs, which start a new execution of the same workflow rather than a new run; the wait ends when the latest execution is terminal. With both ids the workflow is watched and must belong to that run. Pass untilJobKey to return as soon as one job is done instead of the whole target, for example the test job when the deploy job behind it does not matter yet.

This is bounded polling, not a stream. It calls GetRunStatus (or GetWorkflow) every pollSeconds until the target is finished, failed, or cancelled, or until timeoutSeconds is spent, whichever comes first, then returns. It never subscribes to Depot's log or status streams. If the result says timedOut=true the target is still going: call this tool again with the same id to keep waiting; the changes list shows what moved in the meantime. Keep timeoutSeconds below your MCP client's own tool-call timeout, or the client will give up before this tool does.

A run or workflow that is already finished returns immediately after one poll, so this is also a cheap way to check "is it done yet". For the structure use depot_get_ci_run or depot_get_ci_workflow; for why it failed use depot_diagnose_ci_failure.

Fetch a bounded slice of the persisted logs for a Depot CI job attempt.

Try depot_diagnose_ci_failure first. It is cheaper, it already contains the relevant log lines with a diagnosis attached, and it identifies which job actually broke. Use this tool when you need detail the diagnosis did not include: the full traceback, output from a step that did not fail, or a specific pattern.

Defaults to the last 200 matching lines, because failures land at the end of a log. "grep" (case-insensitive substring, not a regex), "stepKey" and "stream" are applied by this server after it fetches pages from Depot, so they reduce what you receive but not what is read: a grep still walks the log page by page, up to DEPOT_MCP_MAX_LOG_PAGES pages (default 20), and is the most expensive way to use this tool. Prefer stepKey or stream, which at least keep the returned window small.

"id" accepts an attempt id, a job id, or a run id. Given a run id this picks that run's failed job (or its last job) and reads the latest attempt, mirroring what "depot ci logs" does.

Paging contract:

• Without a pageToken you get the tail: the last "tailLines" matching lines of what was read. If the page cap stops the walk first, the result says so, the lines are the end of what was read rather than the end of the log, and nextPageToken continues forward from there.

• With a pageToken you get the next window forward: up to "tailLines" lines in order from that point, and a new nextPageToken if more remain. Nothing in a forward window is ever dropped for the character budget; the window just closes early and the token resumes at the exact next line, so following nextPageToken until it is absent yields every line exactly once. That is how to follow a running job's output across turns.

• Pass tokens back verbatim. Some are issued by this server rather than Depot; both are opaque.

• Each line body is capped at 2000 characters ("bodyTruncated" marks the ones that were cut).

Read the step summary a Depot CI job authored for itself — the equivalent of GitHub Actions' $GITHUB_STEP_SUMMARY.

This is markdown the job's own steps chose to publish: test result tables, coverage deltas, lint counts, deployment URLs. When a job writes one, it is usually a far better explanation of what happened than its logs, because a human decided what mattered.

Most jobs write nothing here, and an empty result is normal rather than an error. If it comes back empty, use depot_diagnose_ci_failure for a failure, or depot_get_ci_logs for raw output.

"id" accepts an attempt id, a job id, or a run id.

Read CPU and memory metrics for a Depot CI run, job, or job attempt.

Use this when a job died without a useful error, was killed abruptly, hit an exit code like 137, or is simply slow — the shapes to look for are memory sitting at its limit (an OOM kill) or CPU pinned at 100% for the whole job (under-provisioned runner).

"id" accepts a run, job, or attempt id and the level is inferred; set "level" to pick explicitly. Note that metrics for a still-running attempt grow between calls, so a snapshot time is reported.

Depot does not publish field names for these responses, so this tool returns the metrics it recognises plus the raw document (bounded) so nothing is lost. Very large metrics results are rejected by Depot itself with a resource-exhausted error — ask for a single attempt rather than a whole run if that happens.

List the artifacts a Depot CI run, workflow, job, or attempt uploaded, optionally with signed download URLs.

Use this to find out what a run produced — test reports, JUnit XML, coverage output, built binaries, screenshots from a failed browser test. Filter to one job or attempt by passing its id alongside runId.

Set withDownloadUrl=true to also fetch signed HTTPS URLs, which are minted one request per artifact and capped at 10 per call. This tool never downloads or reads artifact contents; it returns metadata and links only.

Mint a short-lived signed download URL for one Depot CI artifact, by artifact id.

Use this when you already know which artifact you want (from depot_list_ci_artifacts) and need to fetch it: a JUnit report to read the failing test names, a screenshot from a browser test, a built binary. Download it with curl or fetch as soon as you have the URL, since Depot signs it for minutes, not hours.

The URL is a bearer capability. Anyone holding it can download the artifact until it expires, so treat it like a credential: use it immediately and never write it anywhere durable (commit messages, issues, chat, files). This tool returns the URL only; it does not download the artifact or read its contents, and it cannot upload, replace, or delete anything.

To see what a run produced, or to get URLs for several artifacts in one call, use depot_list_ci_artifacts (with withDownloadUrl=true) instead.

Compare two Depot CI runs side by side: which jobs changed status, got slower or faster, used more memory, appeared or disappeared, and which failures are new in the second run versus fixed since the first.

Use this when the question is about the difference between two runs rather than one run on its own: "what regressed between these two commits", "is this failure new or was it already broken on main", "did the retry fail the same way" (a flaky failure produces a different error message across runs; a deterministic one repeats), or "why is this run slower than the last one".

runA is the baseline (older, or known-good) and runB is the run under question; deltas read B minus A. Jobs are matched by their job key, so both runs should come from the same workflow or the matrix will be mostly "only in A" and "only in B". Failure fingerprints come from Depot's failure analysis and are only fetched for the sides that actually failed.

For a single run, use depot_diagnose_ci_failure instead: it explains the failure with diagnosis, suggested fix, and evidence lines, none of which this tool returns.

Explain why a Depot container build failed: locate the step that broke and return its error and the tail of its logs, alongside cache effectiveness for the build.

Use this for "why did my docker build fail". Unlike Depot CI, container builds have no server-side AI diagnosis, so this tool does the legwork an agent would otherwise do by hand: read the build, page through its steps, pick the step that reported an error (or the last step that actually executed), and fetch only that step's logs.

Pass projectId when you know it. Depot's build record does not include a project id and the steps API requires one, so without it this tool has to scan recent builds across your projects, which costs several extra requests. DEPOT_PROJECT_ID works as a default.

Also reports cachedSteps vs totalSteps and secondsSaved, which is the fastest way to see whether a slow build is a cache miss problem rather than a code problem.

Read-only: this cannot start, retry, or cancel a build. Container builds cannot be triggered through Depot's API at all. If asked to start one, say that the user runs "depot build" locally or CI runs it; do not run the CLI on the user's behalf or look for a token to do so.

Show one Depot container build: its status, when it was created, started and finished, how long it ran, and how much of it the cache served.

Use this to check on a specific build by id: "did build X succeed", "is it still running", "how well did the cache do". It is one request and returns quickly, so it is the right way to poll a build that is in progress; call it again after a pause rather than waiting inside a tool.

It does not explain a failure. When the status is failed, error, or canceled, call depot_diagnose_build with the same buildId (and the projectId, if you know it) to find the failing step and its logs. For a list of recent builds use depot_list_builds; for Depot CI runs, which are a different product, use depot_get_ci_run.

List recent container builds for a Depot project, with duration and cache effectiveness for each.

Use this to find a build to diagnose, or to answer "are our builds getting slower" — every row carries cachedSteps, totalSteps and secondsSaved, so a run of builds with a low cache hit ratio is visible immediately without opening the dashboard.

Requires a projectId; DEPOT_PROJECT_ID is used when set, and depot_list_projects lists the options. These are container builds only, not Depot CI runs — use depot_list_ci_runs for those.

List Depot container build projects with their region, runner hardware, and cache policy.

Use this to find a projectId for depot_list_builds, depot_diagnose_build, or depot_list_images, and to check configuration that affects build speed: which region a project builds in, how large its runners are, and how much layer cache it retains before eviction.

These are container build projects. Depot CI runs are organised by repository and workflow instead — use depot_list_ci_runs for those.

Show one Depot container build project's full configuration together with its OIDC trust policies.

Use this to check build capacity and cache retention for a specific project, and to audit which external CI systems are allowed to exchange an OIDC token for Depot credentials — trust policies are the answer to "how does our GitHub Actions workflow authenticate to Depot without a stored token".

Trust-relationship tokens carry project-token permissions, which means they cannot reach the Depot CI API or the Depot API; only container builds and the registry.

List every OIDC trust policy across your Depot container build projects and summarise which external CI identities (a GitHub repository, a Buildkite pipeline, a CircleCI project, a GitLab project) can build into which project.

Use this for access reviews: "who can push builds into our projects without a token", "is a repository we archived still trusted", "does any project trust a repository outside our organization". A project with no trust policies is common and fine; its builds authenticate with a token instead.

Pass projectId to audit one project; otherwise the first 50 projects are checked with one ListTrustPolicies call each. Read-only: adding or removing a trust policy is not offered by this server. Organization token only.

List the project tokens that exist for one Depot container build project: token id, description, and timestamps when Depot provides them. Never the token secret, which Depot only reveals once, at creation, and this server never creates one.

Use this for credential inventory and access reviews: "which tokens exist for this project", "is there a token nobody remembers creating". Pair it with depot_audit_trust_policies for the OIDC side of the same question.

Read-only: creating, rotating, or revoking a token is not offered by this server. Organization token only.

Report Depot usage for a period: container build minutes and minutes saved by caching, GitHub Actions runner minutes by repository and workflow, storage, and agent sandbox minutes.

Use this for cost questions — "what is burning our Depot minutes", "which repo dominates our runner bill", "is the cache actually paying for itself". minutesSaved against minutesBilled is the cache's return on investment; a project with high billed minutes and low saved minutes is where to look first.

This is also the only place Depot exposes managed GitHub Actions runner data through the API, and it is aggregated: there is no per-job runner list.

Pass projectId to scope to one container build project, which returns build counts, duration and layer cache size instead of the organization-wide breakdown. Defaults to the last 30 days.

List every Depot container build project's build count, total build time, and layer cache size for a period, in one call.

Use this for "which project holds the most cache", "which projects are actually building", and "where is our storage going". Rows are sorted by layer cache size, largest first, and carry the project name when depot_list_projects can supply it. For minutes billed and minutes saved by caching use depot_get_usage; for one project's cache health use depot_get_cache_summary.

Organization token only. Defaults to the last 30 days; Depot pages long lists, so re-call with pageToken when nextPageToken is set.

Report the health of one Depot project's layer cache: the retention policy against the current cache size, the cache hit ratio over recent builds, the time the cache saved, and plain-language observations (cache near its size limit, low hit ratio, builds arriving less often than the retention keeps layers).

Use this for "is our cache working", "why are builds not hitting cache", and "are we about to evict layers". It combines depot_get_project (policy), depot_list_project_usage (current size), depot_list_builds (per-build cache counters) and depot_get_usage (minutes billed and saved) so you do not have to.

What it cannot do: Depot's API does not list individual cache entries, so there is no per-layer view, and this server never resets a project's cache. Requires a projectId or DEPOT_PROJECT_ID, and an Organization token.

List the container images stored in a Depot project's registry, with tag, digest, push time, and size.

Use this to check whether a build actually pushed what you expected, to find the digest behind a tag before a deploy, or to see when an image was last refreshed.

Requires a projectId; DEPOT_PROJECT_ID is used when set, and depot_list_projects lists the options.

Read-only: this cannot delete tags or images. Image deletion is deliberately not exposed by this server, since it is irreversible and something may be deploying what you delete.

List the names and scoping of Depot CI secrets. Values are never returned — Depot's API does not expose them at all, by design.

Use this to answer "why can't my job see $FOO". Depot models a secret as one name with several variants, each scoped by repository, environment, branch, and workflow attributes; a job that cannot see a secret usually means no variant matches that job's scope. Compare what this returns against the job you are debugging.

Filtering happens in this server, because Depot's v3beta2 list filters are undocumented. Note that depot.ci.v3beta2 is a beta API and the most likely of Depot's surfaces to change.

List Depot CI variables, their values, and their scoping.

Use this for the same "why can't my job see $FOO" question as depot_list_ci_secrets, and to check that a variable holds what you expect for a given branch or environment. Depot models a variable as one name with several variants, each scoped by repository, environment, branch, and workflow.

Unlike secrets, Depot does return variable values. Because variables are routinely misused to hold credentials, this server redacts any value whose name or content looks like a secret and reports which rule fired, so a redacted value still tells you the variable exists.

Filtering happens in this server. depot.ci.v3beta2 is a beta API and the most likely of Depot's surfaces to change.