Troubleshooting

Symptom	Likely Cause	Resolution
get_conventions returns auth error	Invalid or expired DC_MCP_API_KEY	Check ~/.zshrc has the correct key; run source ~/.zshrc; rotate key via secrets manager if needed
design-system fails to extract	Invalid Figma token or frame URL	Verify FIGMA_API_TOKEN and confirm URLs point to valid frames
Figma MCP returns 403	Desktop app not open, MCP not enabled, or view-only access	Open Figma with design file loaded, enable MCP in Inspect panel, ensure edit access
Playwright screenshots fail	Missing browser binary or @playwright/cli not installed	Run npx @playwright/cli install chromium to install the browser binary
Playwright screenshot timeout	Browser spin-up time lag	Timeout defaults to 60s. If still timing out, check network/proxy settings
upgrade reports wrong server URL	.mcp.json still points to old workers.dev domain	Update the dev-mcp URL to https://dev.mcp.dotcollective.com.au/sse
Server name mismatch after upgrade	.mcp.json uses dc-mcp instead of dev-mcp	Rename the key in .mcp.json from dc-mcp to dev-mcp
Build creates duplicate components	Stale CONVENTIONS.md	Re-read CONVENTIONS.md; update if snippets exist but aren’t listed
MCP servers don’t initialise	Corrupted .mcp.json	Regenerate from a known-good setup output or template
Claude Code uses bash instead of MCP tools	MCP tools not explicitly mentioned	Say “Figma MCP” explicitly in your first prompt
Skill not found	Skill name misspelled or not yet published	Run list_skills to confirm available skills
Shopify dev server unreachable	Port conflict or CLI auth expired	Check for other processes on port 9292; re-run shopify auth
MCP server missing after setup	Auto-install failed for one server	Use the manual install command from the MCP Server Stack, then run claude mcp list
pnpm not found after setup	pnpm not installed globally	Run npm install -g pnpm then retry
Project still using npm after upgrade	upgrade command not yet run	Run upgrade to migrate from npm to pnpm non-destructively