depot-mcp

A small, read-only MCP server for the Depot API.

Depot gives agents a CLI, but no MCP server. This server lets an agent read Depot CI failures, job logs, GitHub Actions jobs on Depot runners, and container builds. The agent does not need the depot CLI in its sandbox.

• Transport: Streamable HTTP, stateless. One endpoint: POST /mcp.

• Auth: Each request sends the caller's own Depot API token as Authorization: Bearer <token>. The server sends that token to Depot and stores nothing.

• Scope: Read-only. No tool can start, cancel, retry or delete anything.

Tools

Depot CI

GitHub Actions on Depot runners

Container builds

Typical flow to debug a failed Depot CI run:

1. ci_list_runs with status: ["failed"], repo and pr.

2. ci_diagnose_failure with targetType: "run" and the run ID.

3. ci_get_job_logs with an attempt ID from the diagnosis. Add stderrOnly or contains to make the output smaller.

ci_get_run does not return jobs or attempt IDs. Use ci_diagnose_failure or ci_get_workflow to get them.

gha_list_jobs uses a 24-hour window when you do not set startAt or endAt. Depot's own default is 30 days, and that can time out on large organizations.

Related MCP server: depot-mcp

Known issues

• gha_search_logs returns 500 internal from Depot. A direct call to api.depot.dev gives the same error, so the fault is in the Depot API. Because of this, gha_get_log_context is not tested: it needs a lineId from gha_search_logs.

• get_build_step_logs can return no lines, also for steps that ran for some seconds. The Depot API itself returns {} for these steps. Check hasLogs and error in get_build_steps first.

Tokens

Use a Depot organization token (Organization settings → API tokens). Organization and user tokens can use every tool. Project tokens can use only the container build tools.

If you use a user token and belong to more than one organization, send X-Depot-Org: <org-id> as well.

Run

pnpm install
pnpm build
pnpm start            # listens on PORT (default 3000)

Or with Docker:

docker build -t depot-mcp .
docker run -p 3000:3000 depot-mcp

Environment variables:

GET /healthz returns {"status":"ok"}.

Put the server behind TLS when you deploy it. The token goes in a request header.

Connect a client

Claude Code:

claude mcp add --transport http depot https://<your-host>/mcp \
  --header "Authorization: Bearer $DEPOT_TOKEN"

Any other MCP client that supports Streamable HTTP and custom headers works the same way.

Development

pnpm dev          # run with reload
pnpm test         # vitest
pnpm typecheck
pnpm smoke PostHog/posthog   # call the tools on a running server with DEPOT_TOKEN from .env

The server calls Depot's Connect RPC API with plain JSON over fetch. Request field names come from Depot's protobuf definitions in depot/proto and depot/cli.