Skip to content
Documentation
Troubleshooting
MCP

MCP

Common issues when connecting AI agents to Valdr over stdio MCP.

MCP host fails to start or respond

Symptom: Your host cannot connect to Valdr over MCP, or requests time out immediately.

Likely cause: The host is not launching valdr pm correctly, is using the wrong working directory, or is pointing at the wrong --pm-home.

Fix:

  1. Confirm your MCP host runs valdr pm, not valdr
  2. Set the MCP server cwd to the repo root if you rely on repo-local worktrees or packs
  3. Verify the configured --pm-home matches the database you expect to use
  4. Fully restart the MCP host after making changes

MCP host exits immediately with a credentials error

Symptom: The host fails to start valdr pm and logs Encrypted startup requires VALDR_DB_USERNAME and VALDR_DB_PASSWORD in non-interactive mode.

Likely cause: The host launches Valdr without a TTY, so Valdr cannot prompt for credentials interactively.

Fix: Add both variables to the MCP server environment:

VALDR_DB_USERNAME=yourname
VALDR_DB_PASSWORD=yourpassword

Then restart the host so it relaunches valdr pm with those values.

MCP tools are missing in the client

Symptom: You can connect to Valdr but expected tools do not appear in the client’s tool list.

Likely cause: The host cached an older tool registry, or you are connected to an instance with a different license tier or configuration.

Fix:

  • Restart the MCP host completely
  • Reconfirm the server command, working directory, and --pm-home
  • If the host has a tool refresh or reconnect flow, run it after restarting Valdr

Compare the client’s tool list with pm_health { detail: true } when your tier permits it. Health lists the MCP tools available at that license tier. For action-based tools, call { action: "help" } and inspect the client’s input schema before using an example from another Valdr version.

pm_health and pm_generate_ulid are plain utility tools. Call them as pm_health {} or pm_generate_ulid {} without an action field.

Repo-local packs or worktrees are not found

Symptom: Agent launches work, but repo-specific behavior is missing, or sessions behave as though they are attached to the wrong repository.

Likely cause: The MCP server is running with the wrong current working directory.

Fix: Set the MCP server cwd to your repo root and reconnect the host.

Tool returns a tier or permission error

Symptom: A tool call is denied because of your current tier.

Likely cause: The connected Valdr instance does not have access to that tool or action.

Fix:

  • Check your license tier in Settings > Settings
  • Compare the tool against the Valdr MCP reference
  • If the host cached an older tool surface, restart it after any license change

Read whether the error concerns your subscription, the session’s permissions, or a required workflow approval. An agent can have a visible tool but lack permission for a particular action. Complete the required action or approval in Valdr UI when the error calls for it.

pm_task search returns projectKey required

Symptom: Calling pm_task { action: "search", query: "..." } fails.

Likely cause: pm_task.search is scoped to a single project.

Fix:

pm_project { action: "list", limit: 10 }
# pick a key from the response, then:
pm_task { action: "search", projectKey: "MYAPI", query: "rate limit" }

pm_prompt list does not include prompt content

Symptom: pm_prompt { action: "list" } returns metadata but not the actual prompt text.

Likely cause: This is intentional. list keeps payloads lightweight.

Fix: Use pm_prompt { action: "get", key: "..." } for a single prompt, or pm_prompt { action: "list_with_content" } if you need full content for every result.

clientRequestId / idempotencyKey errors

Symptom: A call fails because its request ID is missing, or a retry returns an earlier result.

Likely cause: The action requires a request identity, or the supplied identity has already been used. The accepted field and constraints depend on the action.

Fix: For new work, generate an ID with pm_generate_ulid {} and retain it with the arguments. For a retry of the same operation after a timeout or uncertain response, reuse the original ID and unchanged arguments. A fresh ID can launch duplicate work.

pm_generate_ulid {}
# → use the returned ULID in your next call

For session input, inspect the returned receipt and session events. queued means accepted for later delivery; an ambiguous steering receipt is not automatically resubmitted. Do not treat either state as completed agent work.

Tool call returns an error or an empty result

Check the MCP result’s isError, readable content, and structuredContent. Empty task, review, or prompt lists can be successful discovery results. Receiving a response does not mean the requested work succeeded: it may contain isError: true, or an outcome such as close_checked returning tasks_not_done.

Correct validation errors using the action’s help and input schema. If you are unsure whether a change succeeded, inspect the target record before retrying and retain any supported idempotency key. A successful pm_health call confirms the connection and identifies the running server; check provider credentials and action permissions separately.

Old behavior after a Valdr upgrade

Symptom: You upgraded Valdr but MCP still behaves like the old version.

Likely cause: An older Valdr process is still running in the background.

Fix:

# Find running valdr processes
ps -Ao pid,ppid,command | grep '[v]aldr'

# Stop the old one(s)
kill <PID>

Then restart your MCP host so it launches the new version.

Related

StartupProviders & Presets