Claude Desktop & MCP Cheat Sheet

1Install & sign inmacOS · Windows

# download from: claude.ai/download★
Native app for macOS and Windows (there's no official Linux desktop build). Sign in with the same account as claude.ai — your plan (Free/Pro/Max/Team) carries over.
# updates install automatically; relaunch to apply
The app self-updates. Feature availability (Connectors, Extensions, Developer mode) can differ by app version and plan — keep it current.
# the desktop app is NOT Claude Code (that's a separate CLI)
Claude Desktop is the chat GUI + MCP host. Claude Code is the agentic coding tool for the terminal/IDE — different product, also an MCP host.

2Interface & featureswhat's built in

Projects # persistent workspaces with their own knowledge + instructions★
Group chats, upload reference docs (project knowledge), and set custom instructions that apply to every chat in the project.
Artifacts # live side panel for code, docs, HTML, diagrams★
Substantial generated content opens in a dedicated panel you can iterate on — runnable HTML/React previews, editable documents.
Styles · web search · file & image uploads
Styles shape tone/format (Normal, Concise, Explanatory, or custom). Attach files/images with the paperclip; toggle web search per chat.
# model + extended-thinking toggle live under the message box
Pick the model and turn extended thinking on for harder problems right where you type.

3The config fileclaude_desktop_config.json

Settings → Developer → Edit Config★
The reliable way to open (and create, if missing) claude_desktop_config.json — it reveals the file in Finder/Explorer. This is where all local MCP servers are declared.
# macOS ~/Library/Application Support/Claude/claude_desktop_config.json★
The file's home on macOS. It does not exist until you create it (or click Edit Config once).
# Windows %APPDATA%\Claude\claude_desktop_config.json★
On Windows, expand %APPDATA% (usually C:\Users\<you>\AppData\Roaming). Same JSON schema on both platforms.
{ "mcpServers": { } }
The whole file is one JSON object. Servers go under the mcpServers key — empty is valid. ⚠️ It must be strict JSON: no comments, no trailing commas.

4Settings & shortcutsget around fast

Cmd/Ctrl + N # new chat Cmd/Ctrl + K # quick search★
Start a fresh conversation or jump to any past chat instantly.
Cmd/Ctrl + , # open Settings
Settings holds account, model behavior, Connectors, Extensions, and Developer (where Edit Config lives). Enable Developer mode if you don't see it.
# the app can live in the menu bar / system tray for quick access
Exact shortcuts vary by platform & version — check Settings.

5Add a local serverstdio via command/args

{ "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/Documents"] } } }★
The canonical shape: each server is a name → {command, args}. The app launches that process and talks MCP over stdio. Restart Claude Desktop after saving.
"command": "node", "args": ["/abs/path/to/build/index.js"]★
Run your own server the same way. ⚠️ Use absolute paths and an absolute command when possible — the app may not inherit your shell's PATH.
# "server disconnected" right after launch? almost always PATH/pathsgotcha
If npx/uvx/node isn't found, give the full binary path (e.g. /opt/homebrew/bin/npx, or the full node.exe path on Windows). Check the logs (card 15).

6Common serversready-made

npx -y "@modelcontextprotocol/server-filesystem" /path/one /path/two★
Filesystem — read/write files in the directories you list (scoped to exactly those paths). The most-installed first server.
uvx mcp-server-git --repository /path/to/repo
Git — inspect and operate on a repo. Python servers commonly launch via uvx (from uv) instead of npx.
# many first- & third-party servers: Postgres, Slack, GitHub, Puppeteer, memory…
Browse the registry at modelcontextprotocol.io and the reference servers repo. ⚠️ MCP servers run with your privileges — only install ones you trust.

7Secrets & env varskeys into a server

"github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_TOKEN": "ghp_..." } }★
Pass secrets/config via the env object — it becomes the child process's environment. Servers read tokens from there, not from prompts.
# this file stores tokens in PLAINTEXT — treat it like a secretsecurity
Don't commit claude_desktop_config.json to git; lock down file permissions. Prefer short-lived / least-privilege tokens.
"cwd": "/working/dir" # set the server's working directory
Some servers also accept a cwd. Keep the JSON valid — a single syntax error stops all servers from loading.

8Custom connectors & OAuthSettings, no JSON

Settings → Connectors → Add custom connector → paste the remote MCP URL★
Connectors are remote MCP servers reached by URL — no config file, no local process. Available on Claude web, Cowork & Desktop.
# Advanced settings: OAuth Client ID / Client Secret (optional)★
Most connectors authorize via OAuth in the browser; the app walks the flow and stores the grant. Set a client ID/secret under Advanced when the server needs one (header-based or no-auth servers also work).
# built-in connectors (Google Drive, etc.) toggle on directly
Ready-made connectors can be enabled with just a sign-in — no URL. ⚠️ Team/Enterprise: an owner must enable a connector in Org settings → Connectors first.
# Free = 1 custom connector; Pro/Max/Team/Enterprise allow moreplan
A connector is an intermediary that can read and modify data in the connected service per the access you grant — review what you're authorizing.

9Host your own connectora remote MCP server

# a custom connector IS a remote MCP server you host (Streamable HTTP)★build
Implement MCP tools/prompts/resources with an SDK (@modelcontextprotocol/sdk for TS, mcp for Python), expose it at an HTTPS URL, and add it as a custom connector.
# add OAuth for auth (or header/none for an internal server)
Public connectors implement OAuth so each user authorizes their own access; internal ones can use header-based auth or none. The remote server enforces its own permissions.
# one server, every surface: Claude web, Desktop, the API, Claude Code
The same remote MCP server works as a Desktop connector, in Claude web, via the API's mcp_servers parameter, and in Claude Code — build once. Test it with the MCP Inspector (card 15) before listing.

10Directory & scopesdiscover & control

# connectors expose tools, PROMPTS, and RESOURCES — not just tools★
Beyond callable tools, a connector can offer prompts (slash-command templates) and resources (documents/data) you can @-mention to pull into context.
# a connector directory lists vetted remote servers
Browse ready-to-add connectors from a directory; remote (URL) servers are the recommended form for directory listing. Enable with a click + OAuth.
# review requested scopes before authorizing; revoke in Settings
Read the OAuth consent screen — grant the least access that works. Manage/disconnect connectors anytime in Settings → Connectors.
# local (config JSON) · remote (Connectors) · bundled (Extensions)
Three routes to the same MCP capability — a process on your machine vs a hosted URL vs a one-click package. They coexist.

11Install extensionsone-click

Settings → Extensions # install a packaged MCP server (.mcpb)★
Desktop Extensions bundle an MCP server + its runtime into one installable file — no manual JSON, no npx. The app manages its lifecycle (install/update/enable).
# configure keys/paths via the extension's own settings form
Extensions surface their settings in the UI (from the manifest's user_config), so you set tokens/paths through a form instead of hand-editing env. Easiest path for non-developers.
# .dxt was renamed to .mcpb — older files/docs may still say DXTrenamed
The format & toolchain were renamed from DXT (Desktop Extensions) to MCPB (MCP Bundles). .dxt → .mcpb, dxt CLI → mcpb.

12The .mcpb bundlemanifest.json

# .mcpb = a zip of { server code + runtime + manifest.json }★
Like a browser/VS Code extension: everything the local MCP server needs in one archive, so it installs and runs without the user setting up Node/Python.
{ "manifest_version": "0.3", "name": "my-extension", "version": "1.0.0", "server": { "type": "node", "entry_point": "server/index.js", "mcp_config": { "command": "node", "args": ["${__dirname}/server/index.js"] } } }★
manifest.json declares the bundle: manifest_version, name/version, author, and a server block (type: node/python/binary/uv + entry_point + mcp_config). ${__dirname} resolves to the install dir.
"user_config": { "api_key": { "type":"string", "title":"API key", "sensitive":true } }
user_config defines the fields the app prompts for at install — values are substituted into mcp_config (e.g. into env). Optional: tools, prompts, compatibility, icon.

13Build an extensionmcpb CLI

mcpb init # scaffold a manifest.json interactively★MCPB
Install the mcpb CLI (from modelcontextprotocol/mcpb; formerly dxt). mcpb init walks you through creating the manifest.
mcpb pack # bundle the current dir -> my-extension.mcpb★
mcpb pack zips your server + manifest into a .mcpb. Double-click it (or drag into Settings → Extensions) to install.
# distribute the .mcpb file; users install with one click, no CLI
Great for shipping an internal tool to non-technical teammates — they never touch JSON or a terminal. Pair with signing/verification where required.

14Using tools in chatpermissions

# tools appear behind the tools/slider icon by the message box★
Once a server/connector loads, its tools become available. Claude decides when to call them; you see the tool call and result inline. @-mention a connector resource to add it to context.
# Claude asks permission before running a tool★
You approve tool calls — grant once, or "always allow" for that tool. ⚠️ Approving a write/exec tool lets it act on your machine/accounts; read the call before allowing.
# tools not showing up? the server didn't loadgotcha
No tools = the server failed to start (bad JSON, missing binary, crash on launch). Fully quit and reopen the app after any config change, then check logs.

15Debugging serversread the logs

# macOS logs ~/Library/Logs/Claude/ # mcp.log, mcp-server-*.log★
Per-server stderr & connection logs land here — the first place to look when a server won't connect. On Windows they're under %APPDATA%\Claude\logs\.
npx @modelcontextprotocol/inspector node /path/to/server.js★
The MCP Inspector runs a server standalone in the browser so you can test its tools without the desktop app — isolate "is it my server or the config?". Works for remote connectors too.
# test the launch command in a terminal first
Run the exact command + args in a shell. If it errors there, it'll error in Claude — fix paths/deps before blaming the config.

16Tips & ecosystemget the most out

# validate the JSON before restarting (jq . claude_desktop_config.json)★
One misplaced comma silently kills every server. Lint the file after editing — the app won't always tell you it's malformed.
# MCP is an open standard — the same servers work across hosts
Servers/connectors you set up here also work with Claude Code, IDE extensions, the API (mcp_servers), and other MCP hosts. Build/learn once, reuse everywhere.
# start narrow: one filesystem dir, least-privilege tokens/scopes
Grant the smallest scope that works, then widen. Fewer, well-scoped servers & connectors keep the tool list clean and safer.

Claude Desktop & MCP

Outline

App, config & local servers

Connectors & extensions

Use, debug & ecosystem

App & Config

Local MCP Servers

Connectors (Remote MCP)

Desktop Extensions (.mcpb)

Use, Debug & Ecosystem

Worth memorizing