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

	Depot Agent Skills	depot-mcp
Needs the depot CLI installed and logged in	yes	no
Works in clients without SKILL.md support	no	yes
Invocation	agent must retrieve the skill	tool is listed in tools/list
Can mutate Depot (rerun, cancel, reset)	yes, anything the CLI can	off by default; five CI write tools behind DEPOT_MCP_ALLOW_WRITES, each dry-run first
Can mutate Depot (rerun, cancel, reset)	yes, anything the CLI can	three opt-in write tools behind DEPOT_MCP_ALLOW_WRITES, dry-run by default; no rerun, cancel, or reset
Output bounded for a context window	depends on the CLI command	every tool
Maintained by	Depot	community

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:

Tool group	Organization token	User token
depot_whoami	yes	yes
Depot CI: depot_diagnose_ci_failure, depot_list_ci_runs, depot_get_ci_run, depot_get_ci_job, depot_get_ci_attempt, depot_list_ci_workflows, depot_get_ci_workflow, depot_get_ci_logs, depot_get_ci_job_summary, depot_get_ci_metrics, depot_list_ci_artifacts	yes	yes
Depot CI: depot_diagnose_ci_failure, depot_list_ci_runs, depot_get_ci_run, depot_wait_for_ci_run, depot_get_ci_logs, depot_get_ci_job_summary, depot_get_ci_metrics, depot_list_ci_artifacts, depot_get_ci_artifact_url	yes	yes
Depot CI: depot_diagnose_ci_failure, depot_list_ci_runs, depot_get_ci_run, depot_get_ci_logs, depot_get_ci_job_summary, depot_get_ci_metrics, depot_list_ci_artifacts, depot_compare_ci_runs	yes	yes
depot_list_ci_secrets, depot_list_ci_variables	yes	admins and owners only
depot_list_images	yes	yes
depot_list_projects, depot_get_project, depot_list_builds, depot_get_build, depot_diagnose_build, depot_get_usage	yes	no: Depot answers 401 Invalid token, whatever the user's role
depot_list_projects, depot_get_project, depot_audit_trust_policies, depot_list_project_tokens, depot_list_builds, depot_diagnose_build, depot_get_usage, depot_list_project_usage, depot_get_cache_summary	yes	no: Depot answers 401 Invalid token, whatever the user's role
depot_list_projects, depot_get_project, depot_list_builds, depot_diagnose_build, depot_get_usage	yes	no: Depot answers 401 Invalid token, whatever the user's role
Beta: depot_list_sandboxes, depot_get_sandbox, depot_list_registry_repositories, depot_get_registry_image	yes	not tested yet
Project token	runs nothing

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

The buttons register the server and prompt for the token once, storing it as a VS Code secret. Equivalent .vscode/mcp.json (safe to commit: the token is an input, not a value):

{
  "inputs": [
    {
      "type": "promptString",
      "id": "depot-token",
      "description": "Depot Organization token",
      "password": true
    }
  ],
  "servers": {
    "depot": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "depot-mcp"],
      "env": {
        "DEPOT_TOKEN": "${input:depot-token}"
      }
    }
  }
}

Or from a terminal: code --add-mcp '{"name":"depot","command":"npx","args":["-y","depot-mcp"],"env":{"DEPOT_TOKEN":"YOUR_DEPOT_TOKEN"}}'. Copilot Chat in VS Code uses whatever is in mcp.json; use "MCP: Open User Configuration" for a user-level file.

GitHub Copilot coding agent

Repository Settings, Copilot, Coding agent, MCP configuration. Secrets must be Copilot environment secrets whose names start with COPILOT_MCP_:

{
  "mcpServers": {
    "depot": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "depot-mcp"],
      "env": {
        "DEPOT_TOKEN": "$COPILOT_MCP_DEPOT_TOKEN"
      },
      "tools": ["*"]
    }
  }
}

OpenAI Codex CLI

codex mcp add depot --env DEPOT_TOKEN=YOUR_DEPOT_TOKEN -- npx -y depot-mcp

Or in ~/.codex/config.toml. env_vars forwards named variables from your shell so the token need not be written into the file:

[mcp_servers.depot]
command = "npx"
args = ["-y", "depot-mcp"]
env_vars = ["DEPOT_TOKEN", "DEPOT_ORG_ID"]

Gemini CLI

gemini mcp add -e DEPOT_TOKEN=YOUR_DEPOT_TOKEN depot npx -y depot-mcp

Or in ~/.gemini/settings.json. Gemini CLI expands $VAR and ${VAR} inside env:

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

Windsurf

~/.codeium/windsurf/mcp_config.json, or Windsurf Settings, Cascade, MCP Servers, Manage. Use the generic config above.

Zed

settings.json:

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

Cline

Cline panel, MCP Servers, Configure (or ~/.cline/mcp.json for the CLI). The generic config works; Cline also accepts "disabled": false and "autoApprove": ["depot_whoami", "depot_diagnose_ci_failure"] per server.

JetBrains AI Assistant

Settings, Tools, AI Assistant, Model Context Protocol (MCP), Add, then paste the generic config as JSON. If you already configured Claude Desktop, "Import from Claude" picks it up.

Docker

No Node.js on the host. The image is stdio, so -i is required and -t must not be used. Pass the token from your environment rather than on the command line:

docker build -t depot-mcp .
export DEPOT_TOKEN=YOUR_DEPOT_TOKEN
docker run -i --rm -e DEPOT_TOKEN -e DEPOT_ORG_ID depot-mcp

Client config for the image:

{
  "mcpServers": {
    "depot": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "DEPOT_TOKEN", "depot-mcp"],
      "env": {
        "DEPOT_TOKEN": "YOUR_DEPOT_TOKEN"
      }
    }
  }
}

A published image at ghcr.io/akshayjain3450/depot-mcp and a Docker MCP Catalog entry are planned; see Where to find it.

From a clone

Works today, before the npm publish:

git clone https://github.com/akshayjain3450/depot-mcp.git
cd depot-mcp
npm install
npm run build

Then replace "command": "npx", "args": ["-y", "depot-mcp"] in any block above with "command": "node", "args": ["/absolute/path/to/depot-mcp/dist/index.js"]. For Claude Code:

claude mcp add depot --env DEPOT_TOKEN=YOUR_DEPOT_TOKEN -- node /absolute/path/to/depot-mcp/dist/index.js

Checking it works

npx @modelcontextprotocol/inspector npx -y depot-mcp      # or: node dist/index.js

Then, from your agent, ask it to call depot_whoami. That confirms the token, reports which organizations and projects it can see, and warns about the organization ambiguity described under Configuration.

The binary also answers two flags without needing a token:

npx depot-mcp --version   # prints the version from package.json
npx depot-mcp --help      # usage, environment variables, exit codes

Importing the package (import { createServer } from 'depot-mcp') gives you the server factory without starting anything; only the depot-mcp binary opens stdio.

Compatibility

The server speaks stdio only. Anything that can launch a local process and talk MCP 2025-11-25 (or negotiate down to it) works. "Tested" means exercised end to end by a maintainer with a real token; "verified" means the config shape was checked against the vendor's documentation on 2026-09-05 but not run.

Client	Transport	Status	Notes
MCP Inspector	stdio	tested	npm run inspect
CI stdio smoke (initialize + tools/list)	stdio	tested	runs on every commit, Node 20 and 22
Claude Code	stdio	verified	${VAR} expansion in .mcp.json; prompts per call unless allowlisted
Claude Desktop	stdio, .mcpb	verified	honours readOnlyHint for auto-approval
Cursor	stdio	verified	${env:VAR}; one-click deeplink
VS Code / Copilot Chat	stdio	verified	inputs keep the token out of the file; one-click link
GitHub Copilot coding agent	stdio (type: local)	verified	secrets must be prefixed COPILOT_MCP_
OpenAI Codex CLI	stdio	verified	env_vars forwards from the shell
Gemini CLI	stdio	verified	$VAR expansion in env
Windsurf	stdio	verified	generic config
Zed	stdio	verified	context_servers key
Cline	stdio	verified	autoApprove per tool
JetBrains AI Assistant	stdio	verified	can import Claude Desktop config
Docker (any client)	stdio via docker run -i	verified	image built in CI; distroless runtime
Streamable HTTP / remote	not offered		the token would leave the machine; see Security

If you run it somewhere not listed, open an issue with the client name and the config that worked.

Where to find it

Planned distribution, in order of usefulness. Items marked pending need the npm publish first.

Channel	Identifier	Status
npm	depot-mcp	pending (release.yml publishes with provenance on a v* tag)
Official MCP Registry	io.github.akshayjain3450/depot-mcp (server.json)	pending; mcp-publisher publish after npm
Claude Desktop extension	depot-mcp.mcpb on GitHub releases (manifest.json)	pending
Docker MCP Catalog	PR to docker/mcp-registry with a server.yaml pointing at this repo's Dockerfile	pending
GitHub Container Registry	ghcr.io/akshayjain3450/depot-mcp	pending
Smithery	listing only; Smithery dropped hosted stdio servers in September 2025, and this server is stdio by design	pending
Glama, PulseMCP, awesome-mcp-servers	directory listings	pending

Never look for it under @depot/* or dev.depot/*; those namespaces belong to Depot, and this project is not theirs.

Configuration

Every setting is an environment variable, set in your client's config.