depot-mcp: MCP server for Depot (depot.dev)

A read-only Model Context Protocol server for Depot, the container build and CI acceleration service. It gives a coding agent Depot's own answer to "why did CI fail?" and "why did this build fail?", plus the run history, cache effectiveness, registry contents, CI configuration, and usage data behind those answers.

Community project. Not affiliated with, endorsed by, or supported by Depot. Source-available under Apache 2.0 with the Commons Clause; see License.

Not to be confused with: The Home Depot, Chromium's depot_tools, Steam depots, Perforce depots, or any other "depot". This server talks only to api.depot.dev.

Contents

• Why this exists
• Status
• Prerequisites
  • Which token can do what
• Installation
• Compatibility
• Where to find it
• Configuration
• Tools
• Read-only model and security
• Limitations
• Architecture
• Troubleshooting
• Development
• Contributing
• Roadmap
• License

Why this exists

Depot ships a good agent story already, but it is not MCP. Depot's answer is Agent Skills: SKILL.md files that teach an agent to drive the depot CLI, plus a documented CI API and llms.txt. Depot's own post announcing Skills notes two limitations: skills work best in clients that implement the SKILL.md convention, and they are "sometimes notorious for not being automatically used by agents."

This server covers the gaps that leaves:

• Agents without a shell. Skills require a logged-in depot binary on the machine. A tool call does not.
• Clients that don't read SKILL.md. MCP is client-agnostic.
• Reliable invocation. A registered tool with a description is discovered through the protocol rather than hopefully retrieved.
• A read-only boundary. A skill cannot stop an agent from running depot ci rerun. This server can, and does; see Read-only model and security.

The flagship tool is a thin, careful wrapper around something Depot already built: GetFailureDiagnosis, a server-side failure analysis that clusters a run's failures by root cause and returns a diagnosis, a suggested fix, and the evidence lines, already bounded so it fits in a context window. Most of this server's value is exposing that well.

How it compares to Depot Agent Skills

As of 2026-09-05 no standalone Depot MCP server exists (first-party or otherwise, in the official registry, on npm, or on PyPI), and Depot's own guidance for agents without a shell is to call the CI API directly. This server is that API call, shaped for an agent.

Status

• Read-only by default. With DEPOT_MCP_ALLOW_WRITES unset, no tool that can change anything is registered. Setting it adds five Depot CI write tools (cancel run or workflow, cancel job, retry failed jobs, retry one job, rerun workflow), every one of which dry-runs first; see Write tools. Dispatching a workflow is a ninth write tool, optionally limited by DEPOT_MCP_DISPATCH_ALLOWLIST; stopping or killing a sandbox needs the beta flag as well. There is still no delete, secret, or token-minting tool.
• Read-only by default. Without DEPOT_MCP_ALLOW_WRITES no registered tool can change anything. With it, three write tools appear (set or delete a CI variable, create a project), each previewing by default and refusing unsafe requests before any write. There is still no retry, cancel, rerun, dispatch, or token-minting tool.
• Depot CI is beta, per Depot's own documentation. The CI tools are the most valuable ones here and also the most likely to shift under you.
• Four beta tools are opt-in. DEPOT_MCP_ENABLE_BETA=1 adds read-only tools for Depot sandboxes (depot.sandbox.v1) and the Depot registry (depot.registry.v1beta1). Those APIs are published only as protos, one of them beta in its name, so the tools stay hidden unless you ask for them; see Beta.
• Verified against a real Depot organization. Every read tool, prompt, and resource was run live with organization, user, and project tokens; every write tool was dry-run live and, for the CI writes, variables, and project creation, applied for real in a trial organization on 2026-09-07 (npm run verify:apply). The apply paths of dispatch, sandbox stop and kill, project update, and project delete are covered by the verification script but had not yet been applied at release time.
• MCP protocol revision 2025-11-25. This server is built on the @modelcontextprotocol/sdk 1.x line, which speaks 2025-11-25. The current spec revision is 2026-07-28, implemented by the v2 packages (@modelcontextprotocol/server 2.0.0, published 2026-07-28), which also serve 2025-11-25 clients. Every current client negotiates 2025-11-25, so nothing is lost today. Moving to v2 is a planned, contained change: the SDK is imported in nine files and the transport wiring lives in src/index.ts.

Prerequisites

• Node.js 20 or newer (node --version). The Docker image needs no Node on the host.
• A Depot Organization token. Depot dashboard, Organization Settings, API Tokens. A user token from depot login also works but spans every organization you belong to, so set DEPOT_ORG_ID too.
• Project tokens will not work. Depot's own scope matrix excludes them from Depot CI and the API entirely.

Which token can do what

Depot has three kinds of token and they are not interchangeable. Verified live on 2026-09-06, including with a user token belonging to an organization owner:

The full matrix, per tool and per Depot service, with how to obtain each token, is in docs/tokens.md. depot_whoami reports which kind it holds and names the tools that will not work.

Create a dedicated token for this server so you can revoke it independently. Depot has no read-only token scope; read the security section before you paste one anywhere.

Installation

Every client below runs the same command over stdio. The only things that vary are the file the config lives in and how that client lets you keep the token out of the file.

The generic config, which works as-is in Claude Desktop, Cursor, Windsurf, Cline, JetBrains, and most other clients: