9 Common MCP Setup Problems and How to Fix Them (Claude Desktop & Claude Code)

The vast majority of MCP (Model Context Protocol) setup problems fall into nine recurring patterns. This is a complete troubleshooting guide for both Claude Desktop and Claude Code, with a diagnostic flow you can follow when MCP integration with Ganty (or any MCP-enabled SaaS) refuses to work.

Before You Dive In: Five Things to Check First

Before targeted error fixes, run through the 5-step diagnostic above. 80% of issues surface in those five steps. Move on to the nine problem-specific solutions only if those don't help.

Problem 1: Ganty Doesn't Appear in Claude Desktop's MCP Tool List

The most common scenario. Three causes:

• Wrong config file path. macOS and Windows differ — check Step 2 of the diagnostic.
• JSON syntax error. Trailing commas, missing braces, or smart quotes. Validate with jq . config.json.
• Incomplete restart. Closing the window doesn't reload config. Cmd+Q (mac) or tray-icon Quit (Windows) for full shutdown.

Problem 2: 401 Unauthorized

Authentication error checklist:

• Token not revoked (verify in Ganty dashboard → MCP Integration)
• No stray whitespace or newlines when copying the token
• Header format is exactly Authorization: Bearer TOKEN with one ASCII space

Fastest fix: revoke current token → issue fresh one → copy carefully → update config → fully restart client.

Problem 3: JSON Syntax Error in Config

Common mistakes:

// ❌ Trailing comma
{
  "mcpServers": {
    "ganty": { "url": "...", },
  }
}

// ✅ Correct
{
  "mcpServers": {
    "ganty": {
      "url": "https://ganty.app/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

VS Code or jq will surface these in one shot.

Problem 4: Restart Doesn't Take Effect

"Closing the window" ≠ "quitting the app." On macOS, Cmd+Q. On Windows, tray-icon → Quit to kill the background process. Verify with Activity Monitor / Task Manager that no Claude process is lingering before relaunching.

Problem 5: Local MCP Server Doesn't Start

For stdio-style local MCP servers, the most frequent cause is a bad command path. Specify an absolute path in command, or use npx -y @your-org/mcp-server with -y for first-time reliability. Ganty is HTTP-based (remote), so this doesn't apply directly — but other local MCP servers in your config might fail and make Ganty appear broken by association.

Problem 6: Port Conflict (Local MCP Only)

If two MCP servers want the same port, they collide. Set PORT in each server's env or use distinct URLs. Ganty's remote MCP doesn't suffer this.

Problem 7: SSL/TLS Certificate Errors

Rare, but happens in corporate networks with HTTPS-inspecting proxies. Either add your internal CA via NODE_EXTRA_CA_CERTS, or ask network admins to exclude ganty.app from inspection.

Problem 8: Rate Limit (429 Too Many Requests)

Burst requests trigger temporary rate limits. Ganty's MCP API caps at 60 requests/minute per IP. For batch work, implement exponential backoff or space calls out.

Problem 9: Version Mismatch

Older Claude Desktop versions don't support recent (2025+) MCP spec updates. Check app version and update. For Claude Code: claude --version then npm i -g @anthropic-ai/claude-code@latest.

Diagnostic Flow

When stuck, isolate the layer:

1. Curl test: curl -i -H "Authorization: Bearer TOKEN" https://ganty.app/api/mcp
2. 200 → client-side issue (config or restart)
3. 401 → token or Authorization header
4. 403 → token scope insufficient
5. 500/timeout → server-side blip (check status page)

Next Steps

Still stuck? Email support@ganty.app with a screenshot and your token preview (gnty_xxxx...xxxx, never the full token). For basic setup see the MCP integration guide; for usage patterns see 5 MCP examples and how to use Claude Code for project management.