---
title: Troubleshooting
description: Common issues with RAAD, MCP clients, and the CLI — and how to fix them.
order: 6
---

# Troubleshooting

## MCP client won't connect, or `tools/list` comes back empty

1. **Check the toggle.** Settings → Platform Surfaces → "Allow MCP clients" must be on. It's off
   by default.
2. **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.
3. **Restart the client**, not RAAD. Most MCP clients read their config file once, at launch.
4. **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](/docs/mcp) 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](/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](/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](/docs/support) (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](mailto:hello@raad.app).