MCP Connection Failed: Fixing Broken Connectors and Tool Connections in Cowork

You set up a connector, it worked great for a while, and now it just says “connection failed” or the tool shows up as unavailable in your session. MCP connection errors have a reputation for being cryptic, but most of them trace back to one of a short list of causes: the server isn’t running, the auth token expired, the path is wrong, or the app needs a restart. Working through them in order takes about ten minutes.

What MCP Is and Why Connections Break

Model Context Protocol (MCP) is the system Claude uses to talk to external tools and services. An MCP server is a small piece of software that sits between Claude and a specific service (GitHub, a database, a local file indexer, whatever it might be) and translates requests from Claude into API calls that the service understands. When Claude says “search GitHub for issues,” it’s talking to an MCP server, which then talks to the GitHub API.

This layered architecture means there are several places a connection can break:

• The MCP server process itself might not be running.
• Claude’s configuration might point to the wrong path or command for the server.
• The authentication token that the server uses to talk to the external service might have expired.
• A version mismatch between Claude and the MCP server might cause them to misunderstand each other.
• A network issue, firewall, or proxy might block the connection to an external service.

The error you see in Cowork is usually just “connection failed” or “tool unavailable” regardless of which of these is actually the cause. You have to work through them one by one.

Step 1: Restart Claude Completely

Before anything else, quit Claude fully and reopen it. This sounds obvious, but it resolves a surprising share of connector failures. Claude caches connection state, and a stale cached state from a previously failed connection attempt can make a working connector appear broken.

On macOS: Right-click the Claude icon in the Dock and choose Quit. Don’t just close the window. Wait a few seconds, then reopen.

On Windows: Right-click the Claude icon in the system tray and choose Quit or Exit. Then reopen from the Start menu or desktop shortcut.

After restarting, check whether the connector is now showing as connected before trying anything else.

Step 2: Re-authorize the Connector

If restart didn’t fix it, the next most common cause is an expired authentication token. Many services (GitHub, Notion, Google Workspace, Slack, and others) issue tokens that expire after a set period. When the token expires, the MCP server can no longer authenticate to the external service and the connector goes dark.

How to re-authorize:

1. Open Claude and go to the integrations or connectors panel (the exact label depends on your Claude version).
2. Find the connector that’s failing.
3. Click Re-authorize, Connect Again, or whatever the re-auth button is labeled.
4. Complete the OAuth flow in the browser window that opens. You’ll be asked to sign in to the external service and approve access.
5. Return to Claude. The connector should now show as connected.

If no re-authorization button appears, try removing the connector and adding it again from scratch. Go to the integrations panel, remove the failing connector, restart Claude, then add the same connector again as if it were new.

Step 3: Check That the MCP Server Is Running (for Local Servers)

If you’re using a local MCP server (one you installed yourself to connect to a local database, a custom tool, or a self-hosted service), the server process has to be running before Claude can connect to it. Claude doesn’t start local MCP servers automatically; it expects to find them already listening.

How to check on macOS:

1. Open Terminal.
2. Run ps aux | grep mcp to see if an MCP server process is running.
3. If you don’t see it, start it using whatever command or script you set up when you installed it (for example, node /path/to/server/index.js or python /path/to/server/server.py).
4. Restart Claude and try the connector again.

How to check on Windows:

1. Open Task Manager (Ctrl+Shift+Esc).
2. Look in the Processes or Details tab for the MCP server process (node.exe, python.exe, or whatever runtime your server uses).
3. If it’s not running, start it from the command line using the appropriate command.
4. Restart Claude.

If you want the MCP server to start automatically with your computer, you’ll need to add it to Login Items on macOS (System Settings > General > Login Items) or create a startup task on Windows.

Step 4: Verify the Path and Configuration

If the server is running but the connection still fails, the problem might be that Claude’s configuration points to the wrong place. This happens after updates to either Claude or the MCP server, if you moved the server files, or if the original setup had a typo.

Claude stores MCP server configuration in a JSON config file. The location depends on your platform:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

How to check the config:

1. Open the config file in a text editor.
2. Find the entry for the failing server.
3. Check the command field (the path to the executable or script that starts the server). Make sure the path exists and is correct.
4. Check any args (arguments) and env (environment variables) for obvious errors.
5. Save the file and restart Claude.

A common error is a path with a space in it that isn’t properly quoted, or a relative path that only worked in the specific terminal context where the server was first set up. Use absolute paths in the config.

For the current MCP configuration format and schema, check the Anthropic developer documentation and the Anthropic GitHub where MCP tooling is actively developed.

Step 5: Check Logs for the Actual Error

If the above steps haven’t identified the problem, Claude’s logs will usually tell you what’s actually going wrong. The log output is more specific than the “connection failed” message in the UI.

On macOS:

1. Open the Console app (search for it in Spotlight).
2. Filter for messages from Claude.
3. Look for errors that appear around the time the connector fails.

Alternatively, run Claude from the Terminal with logging enabled. Check the Claude Help Center for the current flag to enable verbose logging, as it changes between versions.

On Windows:

1. Open Event Viewer (search in Start).
2. Check Application logs for errors from Claude.
3. Or check %APPDATA%\Claude\logs\ if Claude writes its own log files (the path may vary by version).

Common error messages to look for:

• “ECONNREFUSED” means the MCP server isn’t running or isn’t listening on the expected port.
• “ENOENT” means the path in the configuration doesn’t exist.
• “401 Unauthorized” or “403 Forbidden” means an authentication problem with the external service.
• “version mismatch” or “protocol error” means the MCP server version is incompatible with the current Claude version.

Step 6: Update Claude and the MCP Server

Version mismatches between Claude and an MCP server can cause connection failures that look like generic errors. If Claude received an automatic update recently, an older MCP server might be speaking a slightly different protocol version.

How to update:

1. Check for Claude updates through the app’s menu (Help > Check for Updates or similar).
2. For MCP servers installed via npm: run npm update -g <package-name> or whatever update command applies to the package.
3. For MCP servers installed via pip: run pip install --upgrade <package-name>.
4. For MCP servers from GitHub: pull the latest version and rebuild if necessary.
5. Restart Claude after updating.

Step 7: Network and Firewall Issues

For connectors that reach external services, a network problem or firewall rule can block the connection even when everything else is configured correctly. This is more likely on managed corporate networks than on home networks.

Things to check:

1. Confirm you can reach the external service in a browser (GitHub, Notion, etc.). If the service itself is down or blocked, the MCP connector can’t work.
2. Check the service’s status page. Many services (GitHub, Slack, and others) publish live status at status.github.com or similar URLs.
3. If you’re on a corporate network, ask IT whether outbound connections to the service’s API endpoints are allowed.
4. Try using a different network (phone hotspot) to rule out a network-level block.

Local MCP servers communicate over localhost, so firewall rules for external traffic shouldn’t affect them. However, a security tool that monitors localhost traffic (some endpoint security products do this) can occasionally interfere.

When the Fix Is “Wait for a Patch”

Some MCP connection failures are genuine bugs in Claude, in the MCP server package, or in how a specific service’s API behaves. If you’ve worked through all the steps above and the connector still doesn’t work, check the Anthropic GitHub for open issues related to the specific connector. If someone else has hit the same problem, there may be a known workaround or a fix already in progress. If not, filing an issue there is the right way to get it tracked.

Cowork is under active development, and MCP support in particular has been evolving quickly. A connector that doesn’t work today may have a fix in the next release. For critical workflows, it’s worth having a manual fallback while you wait.