# 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:

```bash
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](/valdr/docs/valdr-mcp/)
- 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:**

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

```text
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:**

```bash
# 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

- [Valdr MCP reference](/valdr/docs/valdr-mcp/)