3.5 KiB

Raw Blame History

Configuration Workflows

Step-by-step workflows for common Claude configuration tasks.

Adding a New MCP Server

Step 1: Install Server

# NPM-based server
npm install -g @modelcontextprotocol/server-filesystem

# Python-based server
cd ~/my-server && uv sync

# Or use npx (no install needed)
npx -y @package/server --help

Step 2: Get Full Paths

which npx           # /usr/local/bin/npx
which uv            # /usr/local/bin/uv
pwd                 # /Users/name/my-server
realpath server.py  # /Users/name/my-server/server.py

Step 3: Add to Config

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "my-server": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "server-package"]
    }
  }
}

Step 4: Restart Claude Desktop

Quit and reopen Claude Desktop to load new configuration.

Step 5: Verify in Logs

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

Look for successful initialization messages.

Setting Up Team Project

Step 1: Create Settings Directory

mkdir -p .claude

Step 2: Configure Marketplaces

Create .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": {
        "source": "github",
        "repo": "company/plugins"
      }
    }
  }
}

Step 3: Add Enabled Plugins

{
  "enabledPlugins": ["plugin-name"],
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": {
        "source": "github",
        "repo": "company/plugins"
      }
    }
  }
}

Step 4: Commit to Repository

git add .claude/settings.json
git commit -m "feat: add Claude Code team configuration"

Step 5: Team Onboarding

When team members open the project in Claude Code and trust the folder:

Marketplaces auto-install
Plugins become available

Configuring Multiple Environments

Development Config

{
  "mcpServers": {
    "dev-database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://localhost/dev"
      }
    }
  }
}

Production Config (Separate Machine)

{
  "mcpServers": {
    "prod-database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "${PROD_DATABASE_URL}"
      }
    }
  }
}

Migrating Configuration

Export Current Config

cp ~/Library/Application\ Support/Claude/claude_desktop_config.json ~/claude-config-backup.json

Import to New Machine

# Copy backup to new machine
cp ~/claude-config-backup.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Update paths for new machine
# Edit file to fix absolute paths

Validate After Migration

jq empty ~/Library/Application\ Support/Claude/claude_desktop_config.json

Best Practices

Security

Never commit credentials to config files
Use environment variables for secrets: "API_KEY": "${MY_API_KEY}"
Set minimal permissions for MCP servers
Review third-party servers before adding

Organization

Group related servers logically
Use descriptive server names
Document required environment variables in README
Maintain separate configs for different environments

Maintenance

Regularly update MCP servers
Review logs for errors periodically
Test servers after updates
Document custom server configurations

3.5 KiB Raw Blame History