Valdr MCP

Valdr exposes its platform as MCP (Model Context Protocol) tools. Agents can read and manage your workspace through structured tool calls, subject to your subscription and the permissions granted to the session.

Use these tools to operate your local Valdr workspace from an MCP client or an agent. Some settings and workflow approvals require you to act in Valdr UI.

Tier access

MCP tool access is gated by your subscription tier:

See the pricing page for product tier details. Each tool page below shows the feature’s tier. Discover the connected server’s tool list before calling it; session and workflow permissions can further restrict an agent’s actions.

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

Most Valdr MCP tools are organized into consolidated groups: an action parameter selects the operation. The two utility tools, pm_health and pm_generate_ulid, take their own parameters without an action field.

Vanguard tools

Sovereign tools

The unified action pattern

For action-based tools, pass action and the action-specific parameters at the top level. The examples below show the tool name followed by its argument object; in your MCP client, select that tool and send the object as its arguments.

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.

Discover the live tool surface

Start every agent integration by asking the running MCP server what it exposes. The compact health check confirms connectivity and returns the registered tool names:

pm_health {}

When you need the verbose live inventory, pass detail: true:

pm_health { detail: true }

The detailed response adds toolsDetailed, a per-tool inventory with descriptions and action summaries for the currently running server. Use that for broad discovery, then call the individual tool’s help action for canonical action details, examples, cautions, and compatibility notes:

pm_task { action: "help" }
pm_session { action: "help" }
pm_provider { action: "help" }
pm_user_tool { action: "help" }

Health lists the MCP tools available at the connected license tier. The client’s tools/list response supplies input schemas; each action-based tool’s help supplies usage guidance. Check both when building a client, because some fields apply only to particular actions.

Connect a client to your workspace

1. Configure a local stdio server with command valdr and arguments ["pm", "--pm-home", "<absolute-pm-home>"], using the same PM home as your Valdr app. See Configure your MCP host for host setup and encrypted-startup credentials.
2. Reconnect the client, call pm_health {}, and check info.dataDir and info.dbPath before writing anything.
3. Discover projects with pm_project { action: "list", limit: 10 }, then use the returned project key in a bounded task search.
4. Inspect help and the target record before changing it. Use returned IDs and keys instead of copying sample identifiers.

These calls operate on the connected local workspace. Connect through valdr pm; the app’s HTTP/API port is not an MCP endpoint.

Key operator patterns

ID vs key duality

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

Use returned keys in agent prompts for readability, and use record IDs where the action requires them. A project key can differ from its task-key prefix: project my-api may contain task MYAPI-42. Sprint membership actions require the task’s id, not its taskKey.

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

Actions that support retries, such as session launches and plan commits, accept clientRequestId or idempotencyKey. Generate an ID for each distinct operation and retain it with the original arguments. Retry that same operation with the same ID; a new ID represents new work and may create a duplicate. Do not assume every mutation supports idempotency.

Use pm_generate_ulid to produce one ID, or pass count to generate a batch. Sample IDs in this reference are illustrative; use live output for new requests and existing record IDs for lookups.

Read results and errors

MCP results may contain readable content and machine-readable structuredContent. Prefer the structured payload for IDs, counts, cursors, and operation receipts. Check isError before treating a call as successful, and inspect action-level outcomes: an accepted session message or a sprint close check does not itself mean the work finished.

An empty successful list is a valid result. On validation errors, correct the parameters. If an action requires permission or human approval, follow the error’s guidance in Valdr UI or the workflow. After an uncertain write, inspect the target state or retry with the same supported request ID before starting new work.

Help action

Every action-based tool supports { action: "help" } — call it to get the canonical, up-to-date list of supported actions, examples, cautions, and compatibility notes 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 the compact tool-name inventory
• Optional verbose tool details when you call pm_health { detail: true }

If this fails, inspect the returned error or host log: connection, startup credentials, and tier denial are different causes. See MCP troubleshooting for the corresponding recovery steps.

Quick smoke test

A read-only sanity check for project, task, and prompt discovery:

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

Successful results, including empty lists, confirm these discovery calls work. They do not prove that launch permissions, provider credentials, or every other tool are configured.

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 Agent Routines with Capabilities for how to compose these tools into agent capabilities