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:

See the pricing page 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

Sovereign tools

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.

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:

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

pm_task { action: "help" }

Health check

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

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 for startup details.

Quick smoke test

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

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 if you haven’t set up your MCP connection yet
• See Build Your Own Workflow for how to compose these tools into agent capabilities