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

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

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: Calls to pm_session, pm_review, pm_audit, or vmp fail because an ID is missing or malformed.

Likely cause: Those operations expect a fresh ULID for idempotency.

Fix: Generate one with pm_generate_ulid {} and use it in the next call.

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

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