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:

{
  "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.

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.

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.

Each Depot API call has an overall deadline of about 40 seconds, with a bounded number of retries (exponential backoff) for unavailable, deadline_exceeded, aborted, and 429 responses. invalid_argument, not_found, permission_denied, and failed_precondition are never retried. A tool that makes several calls (log paging, build diagnosis) can therefore take longer than one deadline; it reports partial results rather than failing outright when a later page times out.

The organization gotcha

This is the single most confusing Depot failure mode, and Depot's own Agent Skill calls it out. A user token spans every organization you belong to. When more than one is visible and DEPOT_ORG_ID is unset, requests resolve against one organization and everything in the others reads as empty rather than as an error. If a list looks wrongly empty, call depot_whoami; it detects exactly this and tells you what to set.

Tools

All 28 always-on tools are prefixed depot_, named depot_<verb>_<noun>, and annotated readOnlyHint: true and destructiveHint: false. Four more read-only tools sit behind DEPOT_MCP_ENABLE_BETA (see Beta); ten reversible write tools behind DEPOT_MCP_ALLOW_WRITES (see Write tools), two sandbox writes behind that flag and the beta flag together, and one irreversible write behind DEPOT_MCP_ALLOW_DESTRUCTIVE on top (see Destructive writes). The writes carry readOnlyHint: false and honest destructiveHint and idempotentHint values. Names are stable: a rename or removal is a breaking change and will be versioned as one.

Diagnosis (start here)

Depot CI

Container builds, projects, registry, usage

Beta (opt-in)

Registered only when DEPOT_MCP_ENABLE_BETA=1. They are read-only like everything else, but they sit on Depot APIs that Depot publishes only as protos (depot.sandbox.v1, depot.registry.v1beta1, beta in its name), so field names, states, and paging can change under them without a Depot changelog entry. Every description says so. Verified live on 2026-09-06 with an Organization token: each RPC answered the JSON binding (empty lists on a trial organization, Depot's own not_found for unknown ids).

Not exposed, deliberately: sandbox creation, command execution, or timeout changes; registry token listing or creation; any deletion. Stopping or killing a sandbox is a write, so depot_stop_sandbox and depot_kill_sandbox exist only when DEPOT_MCP_ALLOW_WRITES is set as well; see Write tools. The fifth beta tool in the roadmap, depot_list_test_results, needs the depot CLI and is not built.

Write tools (opt-in)

Registered only when DEPOT_MCP_ALLOW_WRITES=1. Without the flag they do not exist as far as the client can tell: they are absent from tools/list, and a call to one fails as an unknown tool. depot_whoami reports whether they are registered and names them.

Every write tool works the same way:

1. dryRun defaults to true. The call reads the current state with Depot's read RPCs and returns a preview of what would change, plus the exact arguments to resend.
2. Resend with dryRun: false after the user has confirmed. The tool reads the state again, applies its refusal rules to that fresh state, and only then calls the one mutating RPC. Depot's own 412 answers are translated into a readable message.

Each applied write logs one line to stderr, [depot-mcp write] <tool> <ids> <time>, so an operator can see what an agent changed. The token never appears in it.

Annotations: readOnlyHint: false on all eleven; destructiveHint: true on the cancels, the variable delete, and the sandbox kill; idempotentHint: false on retries, reruns, dispatch, and project creation, which create new attempts, runs, or projects. | depot_update_project | UpdateProject | a call that changes nothing (every value equals the current one); a regionId other than the project's own, since Depot does not move projects; cacheKeepGb or cacheKeepDays below 1. The preview shows the diff, warns when the cache shrinks (eviction) and when the hardware changes (cost), and sends both cache numbers together because Depot reads an omitted one as zero |

Annotations: readOnlyHint: false on all nine; destructiveHint: true on the cancels and the variable delete; idempotentHint: false on retries, reruns, and project creation, which create new attempts, runs, or projects.

What has been verified live. Every write tool has been dry-run against a real Depot organization, so the preview path, the read RPCs it depends on, and every refusal rule have been exercised. The apply path has been exercised for the variable writes, the workflow rerun, and project creation; UpdateProject and DeleteProject have not been called against Depot yet, and npm run verify:apply is where that happens. The request field names for the CI writes are documented by Depot; those for the variable and project writes come from the v3beta2 bindings vendored in Depot's open-source CLI and from depot/proto, so treat the first real apply of each as a verification step.

Destructive writes (second gate)

Some writes cannot be undone, and no dry run makes deleting the wrong thing recoverable. Those sit behind a second flag, DEPOT_MCP_ALLOW_DESTRUCTIVE, which only counts when DEPOT_MCP_ALLOW_WRITES is set too. With writes on and the second flag off, tools/list does not show them and depot_whoami says the destructive gate is off. Each one also needs a confirmation argument that names what is being destroyed, typed by the user rather than copied from a listing.

Annotations: destructiveHint: true, idempotentHint: true. What the delete removes: the project, its layer cache, build history, registry images, trust policies, and project tokens.

Prompts

Seven prompts chain the tools into workflows an agent would otherwise have to work out step by step. Every argument is stripped to the characters its kind can contain (a repository to owner/name, an id to letters, digits, ., _, -) and JSON-quoted before it is interpolated, so a hostile argument cannot rewrite the instructions.

Resources

Four read-only resources expose the same data by URI, for clients that attach context with @ mentions or resource pickers rather than tool calls. Each one calls the same Depot RPC and parser as the matching tool, returns text/plain, respects DEPOT_MCP_OUTPUT_BUDGET, and turns a Depot error into a readable JSON-RPC error. The templates carry no list callback and nothing subscribes: every read is a fresh request.

Output is always bounded

Every tool caps its own output and tells the agent when it truncated:

• Log tools page forward into a ring buffer and return the tail, since GetJobAttemptLogs pages oldest-first with no tail parameter.
• depot_diagnose_ci_failure propagates Depot's own bounds object as plain-language notes, and distinguishes what Depot dropped from what this server dropped, so a partial diagnosis never looks complete.
• Every result respects DEPOT_MCP_OUTPUT_BUDGET.

Read-only model and security

Read the first point carefully.

• Depot has no read-only token scope. An Organization token that can call ListRuns can also call CancelRun, RerunWorkflow, and DeleteProject. Nothing about the credential you hand this server makes it safe. This server's tool registration is the entire safety boundary: it is read-only because it registers no mutating tool unless DEPOT_MCP_ALLOW_WRITES is set, not because the token is restricted. With the flag set, the five write tools exist, each dry-runs first, and each refuses server-side before calling Depot; depot_dispatch_ci_workflow can start a workflow, bounded by DEPOT_MCP_DISPATCH_ALLOWLIST when set, and there is still no tool that deletes a project, image, or secret, or mints a token. Treat readOnlyHint as a hint to the client, not as enforcement.
• Depot has no read-only token scope. An Organization token that can call ListRuns can also call CancelRun, RerunWorkflow, and DeleteProject. Nothing about the credential you hand this server makes it safe. This server's tool registration is the entire safety boundary: it is read-only by default because it registers no mutating tool unless DEPOT_MCP_ALLOW_WRITES is set, not because the token is restricted. The three write tools that flag enables preview by default and refuse unsafe requests server-side, but a dryRun: false call does change Depot. Treat readOnlyHint as a hint to the client, not as enforcement.
• Irreversible writes sit behind a second gate. DEPOT_MCP_ALLOW_DESTRUCTIVE adds depot_delete_project only when DEPOT_MCP_ALLOW_WRITES is also set, and the tool refuses unless confirmProjectName matches the project's current name. Turning writes off turns deletion off with them; see Destructive writes.
• Some operations are permanently out of scope, not merely deferred: ProjectService/ResetProject (deletes all cached data; a plausible-sounding "fix" with an irreversible, invisible, expensive blast radius), CIService/Run (executes arbitrary workflow content on your infrastructure), token and secret writes (CreateToken returns the secret, which would land in a transcript), image and tag deletion, and ShareBuild (creates a public URL; data exposure disguised as a read).
• The token is never logged, echoed, or written to disk. It is read from the environment only, never printed in errors or in depot_whoami. Error messages from the transport layer and from Depot's own error envelopes are scrubbed of the token before they reach the model, in case a misconfigured endpoint echoes request headers. This server does not read ~/.config/depot/depot.yaml, so it cannot pick up ambient credentials you did not intend to give it.
• CI variable values are scrubbed. Depot withholds secret values server-side, but returns variable values verbatim, and variables get misused as secret storage. Values whose name or content looks like a credential are replaced with a placeholder, and the result reports which rule fired so you still know the variable exists.
• Create a dedicated Organization token for this server so you can revoke it independently.
• stdio only, no listening port. The token crosses no network boundary other than TLS to api.depot.dev.
• CI logs are untrusted text. Log lines, step summaries, artifact names, variable values, and Depot's AI diagnoses are derived from repository content, so anyone who can push to a repository that runs on Depot CI can put words in them. This server returns them; it does not act on them. Your agent might. Summaries fence that text between --- begin untrusted CI content --- and --- end untrusted CI content ---, label Depot's diagnosis and suggested fix as unverified, and carry a contentWarning field in structured output. The server instructions tell the model to treat it as data, never as commands.
• Depot stores CLI credentials in plaintext (mode 0600), not the OS keychain: ~/Library/Application Support/depot/depot.yaml on macOS, ~/.config/depot/depot.yaml on Linux. Relevant if you copy a token from there. Note that the CLI prefers that stored login over DEPOT_TOKEN, so the CLI and this server can be looking at different organizations.

How clients treat the annotations differs: Claude Desktop uses readOnlyHint for auto-approval, Claude Code prompts on every call unless the tool is allowlisted, and Cursor uses its own run modes. Report security problems as described in SECURITY.md.

Limitations

• Container builds cannot be started through Depot's API at all, by anyone. Running a build means acquiring an mTLS BuildKit endpoint and transferring the local build context; the depot CLI embeds a BuildKit fork to do it. Builds here are observability only. A human runs depot build, or CI does.
• Container build steps are read over Connect's binary protobuf encoding, not JSON. Depot's JSON binding of GetBuildSteps fails on Depot's side (the server cannot encode its own response), so this server carries a small dependency-free protobuf codec for the two build-step RPCs, built from Depot's published build.proto. As of 2026-09-06, GetBuildStepLogs returns a server-side internal error on both encodings, so depot_diagnose_build reports the failing step and its recorded error but usually not the step's log lines; the result says so explicitly instead of failing.
• depot.ci.v1 has reference docs but no published schema. It is absent from both depot/proto and the Buf Schema Registry. There is nothing to generate types from and nothing to diff for breaking changes. Rather than assert a contract nobody publishes, responses are read through tolerant accessors that accept either camelCase or snake_case, handle protobuf's int64-as-string encoding, and strip enum name prefixes. Missing fields degrade to "unknown" instead of crashing.
• depot_get_ci_metrics returns Depot's raw document alongside the fields it recognises, because Depot documents that these RPCs return CPU and memory summaries without publishing their field names.
• depot.ci.v3beta2 is beta in its name. The secrets and variables tools are the most breakage-prone. Their list filters are undocumented, so filtering happens in this server and the request sent to Depot is empty.
• No log streaming. Depot caps concurrent log streams per token and per organization, and a careless streaming tool could exhaust that for your whole org, including your real CI. This server polls the unary GetJobAttemptLogs instead, which Depot's docs explicitly bless.
• There is no wait_for_run_to_finish tool, deliberately. Long polls fit badly inside a tool-call timeout. Ask for status again instead; the agent can poll across turns.

Architecture

flowchart LR
    Client["MCP client<br/>(Claude Code, Cursor, VS Code, Codex, ...)"]
    Server["depot-mcp<br/>node dist/index.js"]
    API["api.depot.dev<br/>Connect JSON over HTTPS"]

    Client -- "JSON-RPC over stdio<br/>tools, prompts, resources" --> Server
    Server -- "POST /depot.ci.v1.CIService/GetFailureDiagnosis<br/>Authorization: Bearer DEPOT_TOKEN<br/>x-depot-org: DEPOT_ORG_ID" --> API
    API -- "JSON, read through tolerant accessors" --> Server
    Server -- "text summary + structuredContent,<br/>capped by DEPOT_MCP_OUTPUT_BUDGET" --> Client

One process, one credential, no listening port, no protobuf toolchain. Depot's Connect binding is plain JSON over HTTP POST, so the client is a fetch wrapper with retry. Tools are one module each under src/tools/; shared helpers (budget, redact, resolve, ci-target) keep them small and their output predictable. Design notes, the Depot API survey, and the prior-art review live in docs/ and research/.

Troubleshooting

The server writes one line to stderr on startup (depot-mcp 0.1.0 ready on stdio ...); most clients show stderr in their MCP logs.

Development

npm install
npm run typecheck   # tsc --noEmit, strict
npm run lint        # eslint with type-aware rules
npm test            # vitest, no network or Depot account needed
npm run build       # emit dist/
npm run inspect     # build, then open the MCP Inspector
npm run smoke:stdio # handshake + tools/list against dist/, no token needed
DEPOT_MCP_ENABLE_BETA=1 npm run smoke:stdio   # the same with the four beta tools registered

Tests drive a real Client against a real McpServer over the SDK's InMemoryTransport, with fetch stubbed to return recorded fixtures in test/fixtures/. They assert the full round trip: input validation, output-schema conformance, annotations, character budgets, and error translation. The fixtures cover all four GetFailureDiagnosis states (focused_failure, grouped_failures, over_limit, empty), empty results, and Connect error envelopes.

Live check against your own Depot organization

DEPOT_TOKEN=YOUR_DEPOT_TOKEN npm run smoke

This runs read-only calls only, prints what it found, and reports which checks passed, failed, or were skipped. It skips the failure-diagnosis check if your organization has no failed run to analyse; without one, the flagship tool cannot be exercised.

Before a release, npm run verify runs every tool, prompt, and resource against each token kind in .env and prints a cross-token matrix; docs/verification.md explains the matrix, the opt-in apply run, and the Claude Code session test a human does once per release.

Layout

src/
  index.ts          entrypoint: config, stdio transport
  server.ts         McpServer construction and instructions
  config.ts         environment resolution, fail-fast validation
  prompts.ts        the two chained workflows
  depot/
    client.ts       fetch against Depot's Connect JSON binding, with retry
    api.ts          typed RPC surface
    errors.ts       Connect error codes -> actionable messages
    shape.ts        tolerant accessors for an unpublished schema
  lib/
    tool.ts         registration, validation, error translation in one place
    write.ts        the write pattern: dryRun default, preview, refusal, audit line
    budget.ts       character budgets and truncation
    diagnosis.ts    parsing and shaping the GetFailureDiagnosis document
    ci-tree.ts      run -> workflow -> job -> attempt parsing
    ci-detail.ts    GetJob and GetWorkflow parsing, terminal states, attempt counts
    ci-target.ts    loose identifier resolution
    redact.ts       credential scrubbing
    write.ts        the dryRun / preview / refuse / apply shape of every write tool
    build.ts  project.ts  resolve.ts  time.ts
  tools/            one module per tool group; index.ts holds the write and beta gates
                    (beta.ts lists sandboxes.ts and registry-beta.ts)
  tools/            one module per tool group; index.ts holds the write and destructive gates,
                    writes.ts the gated lists, ci-writes.ts the five CI write tools,
                    projects-admin.ts the project update and delete
test/               vitest: unit, tool round-trips over InMemoryTransport, fixtures
docs/               design notes and distribution details
research/           the API and design research this was built from
.github/            CI, release, smoke and metadata scripts, templates
server.json         MCP Registry entry      manifest.json   Claude Desktop .mcpb manifest
Dockerfile          distroless stdio image  .mcp.json.example  Claude Code project config

research/ documents the Depot API, the MCP design decisions, and the prior-art survey this implementation follows. It is worth reading before changing anything non-obvious.

Contributing

Read CONTRIBUTING.md first. The short version: keep it read-only by default and every write behind the gate and its dry run, keep the token out of everything, keep output bounded, test through the MCP client harness, and sign off your commits (git commit -s). Bug reports and feature requests have templates; security issues go through SECURITY.md, not the issue tracker.

License

Apache License 2.0 with the Commons Clause License Condition v1.0. See LICENSE and NOTICE.

In plain words, you may:

• use it, at home or at work, including inside commercial CI pipelines and paid products that happen to use Depot;
• modify it, fork it, and redistribute it, as long as the LICENSE and NOTICE files travel with it;
• contribute changes back under the same terms.

You may not:

• sell it, charge for hosting it, or offer a paid product or service whose value comes entirely or substantially from this server's functionality.

Because of the Commons Clause this is source-available, not open source under the OSI definition. Everything else in Apache 2.0 (patent grant, no warranty, attribution) applies unchanged.

Depot is a trademark of its owner. This project is unaffiliated with Depot Technologies Inc.