MCP servers add real power, but a server that won't connect is frustrating. Work through the usual causes in order and you'll fix most problems quickly.
Start with status
Open a session and type /mcp. This shows each server's connection status and whether it needs a login. Outside a session, run claude mcp list to confirm the server is even registered. If it's missing, it was never added in the scope you're working in.
Inspect the configuration
Check what was actually registered:
claude mcp get airtable
Compare the transport, URL, or launch command against what the server expects. A typo in the URL or the wrong command after -- is a common culprit.
Match the transport
Make sure the transport fits the server. A local server needs stdio with a command to start it; a remote server needs http (or sse if it specifically requires the legacy transport) with a URL. Using the wrong one leads to a server that never comes up.
Check authentication
If the server connects but its tools return permission errors, the auth step probably didn't finish. Use /mcp to sign in again for OAuth servers, or confirm the header token is correct for key-based servers.
Check environment variables
For servers that read a secret from the environment, a missing variable causes silent failures. If you pulled a shared .mcp.json that uses ${API_KEY} expansion, confirm that variable is actually set in your shell before launching Claude Code.
Reset if needed
When a server is misconfigured, the clean fix is often to remove and re-add it:
claude mcp remove airtable
claude mcp add --transport stdio airtable --env AIRTABLE_API_KEY=KEY -- npx -y airtable-mcp-server
Work top to bottom and you'll rarely be stuck for long.
Comments
Be the first to comment.