Claude Desktop MCP setup

Where to configure

Config file locations

macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

Steps

Good setup flow

Quit Claude Desktop completely before editing config.
Open claude_desktop_config.json for your OS (create the file if missing).
Add mcpServers.pickwise with url and headers — HTTP transport is supported on current builds.
Save, reopen Claude Desktop, and check that pickwise appears under MCP servers.
Start a conversation with your task prompt; PickWise tools should be callable by the assistant.

Claude Desktop-specific notes

Claude Desktop logs MCP errors to its developer console — enable if connections fail silently.
Use the same email your workspace admin provisioned in PickWise People.

Template

{
  "mcpServers": {
    "pickwise": {
      "url": "https://mcp.pickwise.dev/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>",
        "X-Pickwise-Client-Id": "<your-work-email>"
      }
    }
  }
}

Example (replace with your values)

{
  "mcpServers": {
    "pickwise": {
      "url": "https://mcp.pickwise.dev/mcp",
      "headers": {
        "Authorization": "Bearer pw_live_7f3a9c2e1b4d8f6a0c5e",
        "X-Pickwise-Client-Id": "jane@yourcompany.com"
      }
    }
  }
}

Good setup checklist

Sign in and create API keys at https://intelligence.pickwise.dev/api-keys — not from chat or task prompts.
MCP endpoint in IDE config is exactly https://mcp.pickwise.dev/mcp over HTTPS (not the setup guide URL).
Authorization uses Bearer <api-key>; X-Pickwise-Client-Id is the same email you use on the portal.
PickWise MCP tools appear in the IDE after a full restart (not just reload window).
Your task standard is published before developers begin work in the IDE (pickwise_begin_task).

Troubleshooting

Common things to debug

Most connection issues are config path, JSON/TOML syntax, or credentials — not PickWise itself.

What you see	Likely cause	What to try
401 Unauthorized or authentication failed	Wrong API key, revoked key, or email header does not match your PickWise account.	Create a fresh key at https://intelligence.pickwise.dev/api-keys. Copy the full pw_live_… value once. Match X-Pickwise-Client-Id to your portal login email exactly.
PickWise tools never appear in the assistant	Config file path is wrong, JSON is invalid, or the IDE was not restarted after editing.	Validate JSON (trailing commas break parsers). Save the file, quit the IDE completely, reopen, and check the MCP server list.
Connection error or timeout	Corporate proxy, offline VPN, or typo in the URL.	Confirm https://mcp.pickwise.dev/mcp is reachable from your machine. Try curl with the same headers if your security team allows it.
Agent runs but policy decisions are not logged	Task prompt missing, standard not published, or a different MCP server is active.	Ensure the task standard is published and the developer uses pickwise_begin_task (or pickwise_load_standard with the standard ID). Ensure only one pickwise entry exists in mcpServers.

Other IDEs

Using a different client?

Cursor VS Code Windsurf OpenAI Codex JetBrains IDEs