depot-mcp

Overview Schema Source Related Servers Discussions Admin

List Depot CI secret names and scoping

depot_list_ci_secrets

Read-onlyIdempotent

List CI secrets with their scoping to debug why a job can't see a secret. Filter by repository, branch, environment, or workflow to match the job's context.

Instructions

List the names and scoping of Depot CI secrets. Values are never returned — Depot's API does not expose them at all, by design.

Use this to answer "why can't my job see $FOO". Depot models a secret as one name with several variants, each scoped by repository, environment, branch, and workflow attributes; a job that cannot see a secret usually means no variant matches that job's scope. Compare what this returns against the job you are debugging.

Filtering happens in this server, because Depot's v3beta2 list filters are undocumented. Note that depot.ci.v3beta2 is a beta API and the most likely of Depot's surfaces to change.

Input Schema

TableJSON Schema

Name	Required	Description
`query`	No	Case-insensitive substring match on the name.
`branch`	No	Keep variants scoped to this branch.
`workflow`	No	Keep variants scoped to this workflow.
`repository`	No	Keep variants scoped to this repository, plus unscoped ones.
`environment`	No	Keep variants scoped to this environment.

Output Schema

TableJSON Schema

Name	Required	Description
`secrets`	Yes
`returned`	Yes
`valuesAvailable`	Yes	Always false: Depot never returns secret values over the API.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.2.1Sep 8, 2026
- addedOutput schema / properties / secrets / items / properties / id
```
Added value: +{
+  "type": "string"
+}
```
- addedOutput schema / properties / secrets / items / properties / variants / items / properties / id
```
Added value: +{
+  "type": "string"
+}
```
First observedv0.1.0Sep 5, 2026

TDQS

A4.3/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnly/idempotent annotations, the description discloses that secret values are never exposed by design, that filtering happens server-side because the API's filters are undocumented, and that the beta API surface is likely to change. These are meaningful behavioral traits that aid safe invocation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the most important fact (names/scoping, no values) and every sentence adds distinct value: use case, scoping model, server-side filtering, and beta API warning. There is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only list tool with an output schema and five well-described optional parameters, the description covers purpose, behavioral constraints, filtering rationale, and API stability. An agent has enough context to select and call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline applies; each parameter already has a clear description. The description only notes that filtering happens server-side, which does not add parameter-specific meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool lists Depot CI secret names and scoping, and immediately notes that values are never returned. This is a specific verb+resource pairing, though it does not explicitly distinguish itself from the sibling depot_list_ci_variables.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a concrete use case: answer 'why can't my job see $FOO' by comparing returned scoped variants against the failing job. It provides clear context but does not name alternatives or state when not to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.