# Setting up Claude Desktop with MCP

Claude Desktop is what I use for architecture thinking, document review and MCP-connected research — when I am not in the codebase.

---

## Install

1. Download from [claude.ai/download](https://claude.ai/download) (macOS or Windows)
2. Sign in with your Anthropic account
3. Complete any organisation SSO if your team uses it

---

## Why Claude Desktop (not only the web app)

- **MCP connectors** — persistent tools (CRM lookup, transcript search, custom APIs)
- **Long documents** — audit reports, SOWs, knowledge base review
- **Projects** — attach standing context for a client or product

Use the web app for quick questions. Use Desktop when tools and files matter.

---

## MCP configuration

Claude Desktop reads `claude_desktop_config.json`:

| OS | Path |
|----|------|
| **Windows** | `%APPDATA%\Claude\claude_desktop_config.json` |
| **macOS** | `~/Library/Application Support/Claude/claude_desktop_config.json` |

Example (adjust paths and env vars):

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\projects\\your-repo"]
    }
  }
}
```

After editing:

1. Save the file (valid JSON — no trailing commas)
2. **Quit Claude completely** (system tray → Exit)
3. Reopen Claude Desktop
4. Look for the hammer/tools icon — connected servers appear there

Download a starter template from `/resources/files/config/mcp-config.example.json`.

---

## What to connect (and what not to)

### Good first servers

- **Filesystem** — scoped to one project folder (skills, prompts, exports)
- **Fetch / web** — read-only URL fetch for docs (not a substitute for API auth)
- **Custom HighLevel MCP** — staging sub-account, read-only tools first

### Add when you need them

- **Fathom** — meeting transcripts into scoping notes
- **Supabase / Postgres** — inspect middleware tables
- **GitHub** — read issues and file contents

### Avoid early

- Write access to production CRM
- Servers with unbounded shell execution
- One mega-server that exposes every API — split by domain

---

## Typical uses in a HighLevel practice

| Task | How |
|------|-----|
| Review a client's workflow export | Filesystem MCP + pasted JSON |
| Draft KB articles from discovery call | Fathom MCP + orchestration methodology |
| Scope an MCP integration | Architecture diagram + API docs in project |
| Write agent skill files | Prompt library templates + skill library patterns |

Always paste **staging** location IDs. Redact PII from transcripts before wider sharing.

---

## Orchestration discipline

Desktop Claude is **operator orchestration** (layer C in the methodology):

- It helps you **design** agents and integrations
- It does not replace **workflow orchestration** (rules) or **agent orchestration** (live customer channels)

Before deploying anything Claude drafted to production:

1. Stage in a test sub-account
2. Run the skill library guardrails
3. Apply audit → stage → apply → hand back

---

## Troubleshooting

| Problem | Fix |
|---------|-----|
| No tools icon | Invalid JSON in config; check commas and paths |
| Server shows red | Wrong `command` path; install Node if using `npx` |
| Windows path errors | Escape backslashes: `C:\\projects\\repo` |
| Tools work but wrong data | You connected prod credentials — rotate and use staging |

---

## Security

- Config file holds env vars — restrict file permissions
- Use separate API keys for desktop experimentation vs production agents
- Do not commit `claude_desktop_config.json` with secrets to git