Troubleshooting
MCP client won't connect, or tools/list comes back empty
- Check the toggle. Settings → Platform Surfaces → "Allow MCP clients" must be on. It's off by default.
- Check the config was written. Click Configure again for your client — it's safe to run more than once, and only ever touches RAAD's own entry.
- Restart the client, not RAAD. Most MCP clients read their config file once, at launch.
- If auto-configure said "can't auto-configure," your client's config file isn't valid JSON. Fix the JSON first (a trailing comma is the usual culprit), then click Configure again — or copy the snippet from the MCP docs into the file by hand.
save_clip (or any write tool) fails with a permissions-sounding error
Write access is a separate toggle from read access, off by default: Settings → Platform Surfaces → "Allow saving and organizing clips." Read access alone isn't enough — that's deliberate, see the security policy.
raad: command not found
The CLI is a symlink at /usr/local/bin/raad, not installed automatically. Settings → Platform
Surfaces → "Install 'raad' to /usr/local/bin." If that button reports an error, /usr/local/bin
may not exist yet or may be root-owned on a Mac that's never run Homebrew — the error message from
that button says which.
⌘V doesn't paste what I selected
RAAD simulates a keystroke to paste, which needs Accessibility permission. System Settings → Privacy & Security → Accessibility → make sure RAAD is listed and enabled. If you just granted it, quit and reopen RAAD once — macOS doesn't always pick up a fresh grant for an already-running app.
Search doesn't find something I know I copied
- Mid-word while typing matches as a prefix automatically — "clipb" finds "clipboard." A trailing space commits the word, so "clipb " (with the space) won't prefix-match anymore.
- A typo retries once automatically — search "clipbaord" and RAAD retries with "clipboard" if the exact query comes back empty, showing a dismissible "Showing results for…" chip when it does. This only applies inside the app; MCP and the CLI don't get spelling correction, since the correction dictionary can be built from content an MCP client should never see (see the security policy).
- Semantic search (search by meaning, not exact wording) needs the on-device embedding model loaded, which happens automatically a few seconds after launch. If it's not available yet, search falls back to exact keyword matching.
- A sealed pinboard's contents never show up in search from outside that pinboard, locked or unlocked — that's the sealing working as intended, not a search bug.
Still stuck
Send feedback from the app (Advanced settings, or Help menu → Send Feedback) — it prefills your RAAD version, macOS version, and which surfaces are enabled, so there's less to type. Or email hello@raad.app.