Fix: MCP Connection Failed

Error Message:

"Failed to connect to MCP server" "Connection refused at localhost:3000" "Tool execution failed: network error" "MCP server timed out waiting for response"

What This Error Means

Claude Cowork can talk to external tools through the Model Context Protocol (MCP). MCP servers are small programs that expose capabilities — reading a Google Drive folder, querying a local database, controlling a browser — that Claude can call during a task. These servers run as separate processes on your machine (or remotely), and Claude connects to them over a local network port.

When you see a connection failure, it means Claude tried to reach an MCP server and got no response. The server might not be running, it might be on a different port, a firewall might be blocking the connection, or the server process might have crashed silently. This is a local networking problem, not a Claude bug.

Root Cause Analysis

The most frequent cause is simple: the MCP server process isn't running. Unlike Claude itself, MCP servers don't auto-start. If you installed a database connector last week and rebooted your machine since then, that server is gone. You need to start it manually or configure it as a launch service. Many users assume that because they set up the integration once, it stays alive permanently — it doesn't.

A second common cause is port mismatch. When you register an MCP server in Cowork's settings, you specify a URL like http://localhost:3000. If the server actually started on port 3001 (because 3000 was already in use by another application), Claude will keep trying port 3000 and fail every time. This happens frequently on developer machines where multiple services compete for common ports. The server logs will show which port it actually bound to — but only if you check them.

A third cause is network interference. Corporate VPNs are notorious for intercepting or blocking localhost traffic. Some VPN configurations route all traffic through a remote gateway, including loopback addresses, which breaks local MCP connections. Security software like Little Snitch (macOS), Windows Defender Firewall, or endpoint protection agents can also block the connection without any visible warning. The MCP server is running, Claude is trying to connect, but something in between is silently dropping the packets.

Real-World Example

A user set up a local PostgreSQL MCP server so Claude could query their development database. It worked perfectly on Friday. On Monday morning, they opened Cowork, asked Claude to "pull the latest user signup counts from the database," and got "Connection refused at localhost:5432." The cause: their machine had rebooted over the weekend for a system update, and the MCP server wasn't configured to start on boot. The server process simply wasn't running. They restarted it with python mcp_postgres.py, and the connection worked immediately.

Step-by-Step Fix

1. Verify the MCP Server Is Running

Open a terminal and check whether the server process is active.

macOS:

ps aux | grep mcp
lsof -i :3000

Windows:

tasklist | findstr mcp
netstat -ano | findstr :3000

If nothing shows up, the server isn't running. Start it manually (e.g., npm run start, python server.py, or whatever your MCP server's start command is). Watch the terminal output — it should print something like Listening on port 3000 or Server started on 0.0.0.0:3000.

2. Confirm the Port Matches

Check what port the server actually bound to, then compare it to what's in Cowork's settings.

  1. Look at the server's startup output in your terminal — it will say which port it's using.
  2. Open Cowork Settings → Integrations (or MCP Servers).
  3. Find the server entry and check the URL. If the server is on port 8080 but the setting says 3000, update the setting to match.
  4. Save and retry the connection.

If port 3000 is taken by another app, either kill that app or configure your MCP server to use a different port, then update the Cowork setting.

3. Test the Connection Manually

Before blaming Claude, verify the server is actually reachable.

macOS / Windows (both):

curl http://localhost:3000/health

Or if your MCP server exposes a JSON-RPC endpoint:

curl -X POST http://localhost:3000 -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"initialize","id":1}'

If curl gets a response, the server is fine and the problem is in Cowork's configuration. If curl also fails, the problem is the server or the network.

4. Check Firewall and VPN

  • VPN: Temporarily disconnect from your corporate VPN and retry. If the connection works without the VPN, your VPN is intercepting localhost traffic. Contact your IT team to add an exception for localhost, or run the MCP server on a different network interface.
  • macOS firewall: Go to System Settings → Network → Firewall. If it's on, click Options and ensure the MCP server process (e.g., node or python) is allowed incoming connections.
  • macOS Little Snitch: Check the rules list for any blocked connections to localhost or 127.0.0.1.
  • Windows Defender: Open Windows Security → Firewall & network protection → Allow an app through firewall. Find your MCP server process and ensure both private and public are checked.

5. Restart Cowork's Connector Bridge

Sometimes the internal bridge that manages MCP connections crashes or gets into a bad state, even though your server is running fine.

  1. Fully quit Claude Cowork (not just close the window — use Cmd+Q on macOS or Quit from the system tray on Windows).
  2. Wait 10 seconds.
  3. Relaunch Cowork.
  4. Wait 30 seconds for background services to initialize before retrying.

Common Pitfalls

  • Forgetting to restart the server after a reboot. MCP servers don't survive reboots unless you set up a launch agent (macOS) or scheduled task (Windows). If you reboot often, configure auto-start.
  • Using localhost vs 127.0.0.1. Some MCP servers bind to 127.0.0.1 only, while localhost might resolve to ::1 (IPv6) on your machine. If the connection fails, try switching the URL in settings between localhost and 127.0.0.1.
  • Port conflicts with other dev tools. Ports 3000, 8080, and 5173 are commonly used by dev servers. If your MCP server fails to start because the port is busy, it may silently fall back to another port or crash. Always check the startup logs.
  • Assuming the error is on Claude's side. 90% of MCP connection failures are local server or network issues. Always check the server process first.

Prevention Checklist

  • Configure your MCP servers to auto-start on boot (launchd on macOS, Task Scheduler on Windows).
  • Document the exact port each MCP server uses in a local README.
  • Add firewall exceptions for your MCP server processes before you need them.
  • If on a corporate VPN, test MCP connections with the VPN both connected and disconnected.
  • Keep a one-line curl health check command handy for each server so you can quickly verify it's alive.
  • After any system update or reboot, verify MCP servers are running before starting a Cowork session.