Connecting to Claude Desktop

~22 min · claude-desktop, config, integration, debugging

Level 0Curious Reader

0 XP0/48 lessons0/14 achievements

0/100 XP to next level100 XP to go0% complete

Claude Desktop is the canonical MCP host for personal use. It reads a JSON config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS; analogous on other platforms) listing every server it should launch on startup. A server entry names the launch command, args, and optional environment variables.

The end-to-end flow: write your server, add an entry to the config, restart Claude Desktop, see your server's tools appear in the model's tool menu. The first connection is where most early-stage bugs surface — usually a stdout pollution issue (Track 6) or a missing dependency in the launch environment.

The other trap is environment variables. Claude Desktop launches your server in a near-empty environment; $HOME is set, but most others are not. If your server needs an API key, pass it explicitly through the env field of the config or read it from the OS keychain inside the server. Do not rely on shell-set variables — they are not there.

Code

claude_desktop_config.json entry·json

{
  "mcpServers": {
    "my-tools": {
      "command": "uvx",
      "args": ["my-mcp-server"],
      "env": {
        "STRIPE_API_KEY": "sk_live_..."
      }
    },
    "github": {
      "command": "uvx",
      "args": ["github-mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_..."
      }
    }
  }
}

Debug log location·bash

# macOS
tail -f ~/Library/Logs/Claude/mcp.log
tail -f ~/Library/Logs/Claude/mcp-server-my-tools.log

# 'mcp-server-my-tools.log' captures stderr from your server, which is
# where you should be sending diagnostics anyway.

External links

Exercise

Add your tiny server to claude_desktop_config.json. Restart Claude. Ask the model to use one of your tools. Watch the per-server log scroll while the model invokes the tool. The first time you see your own diagnostic line follow a real model decision is the moment the protocol stops being abstract.