MCP Server Connection Refused Fix

Understanding MCP Connection Refused Errors

A "connection refused" error means your MCP client attempted to connect to a server over the network but the connection was actively rejected. This is different from a timeout (no response) - connection refused means something is listening but refusing, or nothing is listening at all. The typical error output looks like:

Error: connect ECONNREFUSED 127.0.0.1:3000
MCP server connection failed: Connection refused

Or in HTTP-based transports:

Failed to connect to MCP server at http://localhost:3000/mcp
Error: fetch failed - ECONNREFUSED

This guide covers every cause and fix for Claude Desktop, Cursor, VS Code, and other MCP clients.

Cause 1: Server Not Running

The most obvious cause - the server process hasn't started or has crashed. For HTTP/SSE-based MCP servers, the server must be running before the client tries to connect.

How to Check

# Check if anything is listening on the expected port
lsof -i :3000        # macOS/Linux
netstat -an | findstr 3000   # Windows

# Check if the server process is running
ps aux | grep mcp    # macOS/Linux
tasklist | findstr mcp       # Windows

Fix

Start the server manually first to verify it works:

# For Node.js servers
npx -y @modelcontextprotocol/server-example

# For Python servers
uvx my-mcp-server

If the server crashes immediately, check its output for errors. Common issues include missing dependencies or incorrect configuration.

Cause 2: Port Conflicts

Another process is already using the port your MCP server needs. This is especially common with development servers on ports 3000, 8000, or 8080.

# Find what's using port 3000
lsof -i :3000
# Output: node    12345 user   22u  IPv4 ...

# Kill the conflicting process
kill 12345

# Or use a different port in your MCP server config

Cause 3: Wrong Transport Configuration

MCP supports two transport types: stdio (local process) and Streamable HTTP (network). Using the wrong one causes connection refused errors.

stdio vs Streamable HTTP

Most MCP servers use stdio transport - the client spawns the server as a child process and communicates via stdin/stdout. If you configure a stdio server with an HTTP URL, you'll get connection refused because no HTTP server is running.

// WRONG - trying to connect to stdio server via HTTP
{
  "mcpServers": {
    "filesystem": {
      "url": "http://localhost:3000/mcp"  // This server doesn't serve HTTP!
    }
  }
}

// CORRECT - stdio transport
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    }
  }
}

Cause 4: Firewall Blocking

Firewalls can block localhost connections, especially on corporate machines or when running servers in containers.

macOS

# Check if macOS firewall is blocking
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate

# Temporarily disable to test
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --setglobalstate off

Windows

# Check Windows Firewall
netsh advfirewall show allprofiles

# Add exception for your MCP server port
netsh advfirewall firewall add rule name="MCP Server" dir=in action=allow protocol=TCP localport=3000

Linux

# Check iptables
sudo iptables -L -n

# Allow localhost connections (usually already allowed)
sudo iptables -A INPUT -s 127.0.0.1 -j ACCEPT

Cause 5: Docker Networking Issues

Running MCP servers in Docker introduces networking complexity. The most common mistake is using localhost from inside a container, which refers to the container's own loopback, not the host machine.

# WRONG - container can't reach host's localhost
docker run -p 3000:3000 my-mcp-server
# Client config pointing to localhost:3000 won't work if the server
# inside the container binds to 127.0.0.1

# FIX - bind to 0.0.0.0 inside the container
docker run -p 3000:3000 my-mcp-server --host 0.0.0.0

For Docker Compose setups, use the service name as the hostname instead of localhost. See our guide on Docker deployment for detailed examples.

Cause 6: SSL/TLS Certificate Issues

If your MCP server uses HTTPS and the certificate is self-signed or expired, the client will refuse the connection:

Error: self-signed certificate in certificate chain
ECONNREFUSED (SSL)

For local development, use HTTP instead of HTTPS. For production, ensure your certificates are valid and trusted. Some clients support environment variables to skip certificate verification (not recommended for production).

Client-Specific Fixes

Claude Desktop

After fixing the connection issue, restart Claude Desktop completely - close all windows and quit the app. Check logs at ~/Library/Logs/Claude/mcp*.log (macOS) for detailed error output.

Cursor

In Cursor, open Settings > MCP to see server connection status. Cursor shows a red indicator for connection failures. Click the server name to see the error details.

VS Code

In VS Code, open the Output panel and select the MCP channel. The connection error with full details will be logged there. You may need to reload the window after fixing the issue.

Step-by-Step Diagnosis

1. Identify the transport - Is it stdio or HTTP? Check your config file.
2. For stdio - The error is probably spawn ENOENT, not connection refused. Verify the command works manually.
3. For HTTP - Verify the server is running and the port is accessible with curl http://localhost:PORT/mcp.
4. Check firewall - Temporarily disable firewalls to rule them out.
5. Check Docker - If using containers, ensure port mapping and 0.0.0.0 binding.
6. Restart client - Fully restart your MCP client after fixing the issue.

Security Considerations

When fixing connection refused errors, be careful not to over-expose your MCP servers. Binding to 0.0.0.0 makes the server accessible from any network interface, not just localhost. For security best practices, see our MCP Server Security Guide.