# Valdr MCP
Valdr exposes its entire platform as MCP (Model Context Protocol) tools. This is the layer that turns Valdr from a UI into a **programmable control plane for AI agents** — the same actions you take in the UI are available to agents as structured tool calls.

Every project you create, every knowledge source you attach, every task you plan, every session you launch, every review you publish — all of it is backed by MCP tools. When you build an agent with Valdr, you're composing calls from this surface.

## Tier access

MCP tool access is gated by your subscription tier:

| Tier | MCP Access |
|------|------------|
| **Raider** (Free) | No MCP access — UI-driven only |
| **Vanguard** | Full PM tools — projects, tasks, sprints, reviews, agents, capabilities, prompts, audits |
| **Sovereign** | Everything in Vanguard plus Workspace Knowledge, session control, task launching, planning (vmp), and provider management |

See the [pricing page](/#pricing) for tier details. Each tool page below shows its required tier. Tools tagged **Sovereign** are gated even if the consolidated tool appears available — specific actions enforce the underlying tier.

## Why this matters for agent design

The MCP surface is how your agents:

- **Read workspace state** — discover projects, tasks, sprints, and agent registries
- **Manage Workspace Knowledge** — attach docs and code, ingest them, search them, and run symbol-aware code map queries
- **Mutate state safely** — create tasks with structured acceptance criteria, transition status, link tasks to sprints
- **Orchestrate other agents** — launch sessions, assign reviewers, start audits, score work
- **Manage their own context** — hot-load capabilities, prompts, and durable agent memory on demand

**An agent is only as capable as the tools it can call.** Understanding this surface is how you build agents that go from "chatbot with file access" to "automation that runs your sprint."

## Tool groups

Valdr MCP tools are organized into consolidated groups — each tool accepts an `action` parameter that selects the specific operation:

### Vanguard tools

{{< cards >}}
  {{< card link="./health/" title="pm_health & pm_generate_ulid" subtitle="Vanguard · Health checks and ULID generation" icon="heart" >}}
  {{< card link="./projects/" title="pm_project" subtitle="Vanguard · Projects, repos, and project comments" icon="folder" >}}
  {{< card link="./tasks/" title="pm_task" subtitle="Vanguard · Task lifecycle, checklists, comments, events" icon="clipboard-list" >}}
  {{< card link="./sprints/" title="pm_sprint" subtitle="Vanguard · Sprint creation, linking, hierarchy" icon="clock" >}}
  {{< card link="./reviews/" title="pm_review" subtitle="Vanguard · Review workflow (some Sovereign actions)" icon="check-circle" >}}
  {{< card link="./audits/" title="pm_audit" subtitle="Vanguard · Auditor launches, context, score ingestion" icon="shield-check" >}}
  {{< card link="./agents/" title="pm_agent" subtitle="Vanguard · Agent registry, capabilities, prompt bindings" icon="user-group" >}}
  {{< card link="./capabilities/" title="pm_capability" subtitle="Vanguard · Reusable capability definitions" icon="cube" >}}
  {{< card link="./prompts/" title="pm_prompt" subtitle="Vanguard · Prompt library with roles and agent bindings" icon="document-text" >}}
{{< /cards >}}

### Sovereign tools

{{< cards >}}
  {{< card link="./sessions/" title="pm_session" subtitle="Sovereign · Agent session lifecycle and task launching" icon="play" >}}
  {{< card link="./knowledge/" title="pm_knowledge" subtitle="Sovereign · Workspace knowledge, search, ingest, and code map" icon="server" >}}
  {{< card link="./providers/" title="pm_provider" subtitle="Sovereign · Launcher presets and provider defaults" icon="switch-horizontal" >}}
  {{< card link="./planner/" title="vmp" subtitle="Sovereign · Valdr Mini-Planner plan drafts and commits" icon="pencil-alt" >}}
{{< /cards >}}

## The unified action pattern

Every Valdr MCP tool uses the same call pattern: pass an `action` field to select the operation, then supply action-specific parameters.

```text
pm_task { action: "create", projectKey: "my-api", title: "Add rate limiting" }
pm_task { action: "search", projectKey: "my-api", status: "in_progress", limit: 20 }
pm_task { action: "change_status", taskKey: "MYAPI-42", to: "in_review" }
```

This keeps the tool count low (one tool per domain) while exposing the full surface area of each resource type.

## Key operator patterns

### ID vs key duality

Most resources support lookup by either ID or human-readable key:

| Resource | Key format | Example |
|----------|-----------|---------|
| Projects | `key` | `"MYAPI"` |
| Tasks | `taskKey` | `"MYAPI-42"` |
| Sprints | `sprintId` | `"01HXYZ..."` |
| Agents | `id` or `handle` | `"sigrid"` |
| Capabilities | `id` or `key` | `"review.quality-gate"` |
| Prompts | `id` or `key` | `"coder.workflow"` |
| Sessions | `sessionUlid` | `"01HABC..."` |

Use keys in agent prompts and capability definitions — they're stable, human-readable, and survive migrations.

### Metadata-only list vs full get

Some tools return lightweight summaries on `list` to keep context windows manageable:

- **`pm_prompt { action: "list" }`** — returns id, key, role, name, tags, agentCount (no content)
- **`pm_prompt { action: "get", key: "..." }`** — returns full prompt content
- **`pm_prompt { action: "list_with_content" }`** — list with content when you explicitly need it

This pattern appears throughout the surface: discover with `list`, drill in with `get`.

### Idempotency and client request IDs

Long-running and mutating operations (session launches, plan commits) accept `clientRequestId` or `idempotencyKey` parameters. Pass a stable ULID so repeated calls don't create duplicates if an agent retries.

Use [`pm_generate_ulid`](./health/#pm_generate_ulid) to produce these IDs — don't generate them yourself. The tool takes no parameters and returns a fresh ULID ready for use in any idempotent operation.

### Help action

Every tool supports `{ action: "help" }` — call it to get the canonical, up-to-date list of supported actions and parameters directly from the MCP server.

```text
pm_task { action: "help" }
```

## Health check

Before your agents make any calls, verify the MCP server is healthy:

```text
pm_health {}
```

Expected response:

- `status: "ok"`
- Runtime metadata including tool inventory and `dbPath`

If this fails, the MCP server isn't reachable and nothing else will work. See [Getting Started](/valdr/docs/getting-started/install/) for startup details.

## Quick smoke test

A three-call sanity check to verify the full surface is wired up:

```text
pm_project { action: "list", limit: 5 }
pm_task { action: "search", projectKey: "<key-from-above>", limit: 5 }
pm_prompt { action: "list", search: "valdr", limit: 10 }
```

If all three return results (or empty arrays without errors), your MCP integration is ready.

## Next steps

- Pick a tool group from the cards above to see its full action reference
- Read [Configure Valdr](/valdr/docs/getting-started/configure/) if you haven't set up your MCP connection yet
- See [Build Your Own Workflow](/valdr/docs/getting-started/workflows/) for how to compose these tools into agent capabilities