When connections fail
Full Lesson Reference
MCPs, CLIs, and database connections fail sometimes. Auth expires, platforms change, keys rotate, networks blip. This lesson is the diagnostic routine for connection issues.
Problem 1: "Authentication failed"
Most common. OAuth tokens expire, API keys get rotated, someone logged into the account elsewhere.
Fix
The [platform] MCP says authentication failed. Help me reconnect - walk me through re-authenticating.
Claude walks you through the OAuth flow or API key refresh. Usually 30 seconds.
Problem 2: "Platform not responding"
The platform itself is having issues - Google Ads API outage, Meta's infrastructure is flaky .
Fix: wait. Most outages resolve in 5-30 minutes.
Is there a known outage for [platform]? Check their status page.
Claude checks the platform's status page if available. Tells you to wait or alternative approaches.
Problem 3: "Rate limit hit"
You've made too many requests in a short period. Platform throttles you.
Fix: wait a few minutes. Or batch smaller
Hit rate limit on [platform]. Spread the remaining requests over the next few minutes + retry with backoff.
Claude paces the requests instead of hammering.
Problem 4: "Wrong account / wrong data"
You're getting data but it's for the wrong client or account.
Fix: check the account config in .mcp.json or project CLAUDE.md:
Show me the account IDs configured for this project. Confirm we're using the right one for [client].
If wrong, update project CLAUDE.md with the correct account ID.
Problem 5: "gh: command not found" / CLI missing
The CLI tool Claude needs isn't installed on your machine.
Fix
The [CLI] isn't installed. Install it for me.
Claude installs via Homebrew (Mac) or the relevant installer.
Problem 6: Supabase memory can't connect
/startup fails because memory isn't loading.
Fix
Test my Supabase memory connection. Can Claude Code reach the database using the credentials in my .env?
Claude tests the connection + reports the specific error. Common causes:
- .env file missing or .env not in project root
- SUPABASE_URL or keys incorrect
- Supabase project paused (free tier pauses after inactivity)
Problem 7: MCP loads but returns empty data
Connection works, auth works, but queries return nothing.
Common causes
- Date range in your query is outside available data
- Account has no activity in that period
- Wrong account (see Problem 4)
Fix
The [platform] query returns empty. Show me: the exact query sent, the account being used, and the date range. Then try a broader query to confirm the connection works at all.
Problem 8: Too many MCPs loaded / token bloat
Session feels slow, context fills too fast.
Fix: Module 13 Lesson 2. Audit + trim.
The connection diagnostic routine
- Check what's connected: /mcp or "show me active MCPs"
- Test the specific connection that's failing
- Check credentials in .env
- Check account IDs in project CLAUDE.md
- If still broken, disconnect + reconnect the MCP fresh
Restart Claude Code itself
If connections are misbehaving across multiple MCPs
/wrapup Close the terminal. Quit Claude Code completely. Open a new terminal. Start fresh. Often resolves state issues.
Restart the machine
For persistent issues: shut down the laptop fully (not sleep), wait 30 seconds, start up again. Clears OS-level network state.
Escalation path
- Try the fix for the specific problem above
- Try disconnecting + reconnecting the MCP
- Try a fresh Claude Code session
- Try restarting your machine
- Check the platform's official status page
- Ask in your team's Slack / community - someone's probably hit it before
Action items
☐ Memorise: auth failures are the most common issue
☐ Know the diagnostic routine: check connection → test → check creds → reconnect → restart
☐ When stuck, try a fresh session + restarted machine before escalating Next lesson: Glossary of key terms.
Exercises
- Review the concepts covered in this lesson: When connections fail.
- Write down your key takeaway from this lesson.
- Practice running any commands or prompts mentioned above inside your terminal.