Depot (depot.dev)

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

A Model Context Protocol server, read-only by default, for [Depot](https://depot.dev), 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 ten write tools, every one of which dry-runs first and refuses unsafe requests before any write: cancel run or workflow, cancel job, retry failed jobs, retry one job, rerun workflow, dispatch workflow (optionally limited by DEPOT_MCP_DISPATCH_ALLOWLIST), set or delete a CI variable, create project, update project; see Write tools. Stopping or killing a sandbox needs the beta flag as well, and deleting a project needs DEPOT_MCP_ALLOW_DESTRUCTIVE on top; see Destructive writes. There is no reset, secret-writing, 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 every write except the two sandbox tools was applied for real in a trial organization on 2026-09-08 (npm run verify:apply), including dispatch, project update, and project delete. Sandbox stop and kill are covered by the verification script but have only been dry-run, because the trial organization had no sandbox to stop.
• 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:

{

"mcpServers": { "depot": { "command": "npx", "args": ["-y", "depot-mcp"], "env": { "DEPOT_TOKEN": "YOUR_DEPOT_TOKEN" } } } }

Add "DEPOT_ORG_ID": "..." to env if your token can see more than one organization. Every tool is prefixed depot_, and tool names are stable across releases.

Claude Code

claude mcp add depot --scope user --env DEPOT_TOKEN=YOUR_DEPOT_TOKEN -- npx -y depot-mcp

Or commit a .mcp.json at the repository root so the whole team gets it. Claude Code expands ${VAR} and ${VAR:-default} in command, args, env, url, and headers, so the token stays in each developer's shell environment and out of git. Copy .mcp.json.example:

{

"mcpServers": { "depot": { "type": "stdio", "command": "npx", "args": ["-y", "depot-mcp"], "env": { "DEPOT_TOKEN": "${DEPOT_TOKEN}", "DEPOT_ORG_ID": "${DEPOT_ORG_ID:-}" } } } }

Claude Code prompts on every MCP tool call regardless of readOnlyHint. To stop being asked, allow the read-only tools in .claude/settings.json: "permissions": { "allow": ["mcp__depot__*"] }.

Claude Desktop

Two options.

Extension bundle (one click). Download depot-mcp.mcpb from the releases page, open it with Claude Desktop (or Settings, Extensions, Advanced settings, Install extension), and paste the token into the settings form. The token field is marked sensitive in manifest.json, so Claude Desktop stores it in the OS keychain rather than in a JSON file.

Manual JSON. Edit ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows and add the generic config above.

Cursor

The button pre-fills the server; fill in DEPOT_TOKEN when Cursor shows the config. Or edit ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project). Cursor resolves ${env:NAME} in command, args, env, url, and headers, so a committed project file can read the token from the environment:

{

"mcpServers": { "depot": { "command": "npx", "args": ["-y", "depot-mcp"], "env": { "DEPOT_TOKEN": "${env:DEPOT_TOKEN}" } } } }

VS Code and GitHub Copilot

[](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522depot%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522depot-mcp%2522%255D%252C%2522env%2522%253A%257B%2522DEPOT_TOKEN%2522%253A%2522%2524%257Binput%253Adepot-t