# Troubleshoot: MCP Connection Refused or Timeout Errors

> Troubleshooting guide for MCP connection refused or timeout errors, including port conflicts, firewall settings, and network policy issues.

---

## Content

# Troubleshoot: MCP Connection Refused or Timeout Errors

When MCP Server starts successfully but cannot connect, or timeout errors occur, this guide helps troubleshoot network-level issues.

## Symptoms

- MCP Server starts but tools cannot be called
- "Connection refused" error
- "Timeout" or "ETIMEDOUT" error
- Unstable connection

## Troubleshooting Steps

### Step 1: Check Port Usage

```bash
# macOS/Linux
lsof -i :3000

# Windows
netstat -ano | findstr :3000
```

### Step 2: Check Firewall

**macOS Firewall**
```bash
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate
```

### Step 3: Check Network Policy

**Proxy Settings**
```bash
echo $HTTP_PROXY
echo $HTTPS_PROXY
unset HTTP_PROXY  # Test without proxy
```

### Step 4: Check Server Listen Address

Ensure server listens on `127.0.0.1` or `localhost`, not `0.0.0.0`

### Step 5: Test Connection

```bash
curl http://localhost:3000/health
nc -zv localhost 3000
```

## Quick Reference

| Error | Cause | Solution |
|-------|-------|----------|
| Connection refused | Port not listening | Check service status |
| ETIMEDOUT | Network timeout | Check network/proxy |
| ECONNRESET | Connection reset | Check server logs |

## Next Steps

- [Python Environment Issues](TRANS-003)
- [Node.js Environment Issues](TRANS-004)
- [Filesystem Configuration](TOOL-FS-001)

## Q&A

**Q: What does Connection refused mean?**

Client tried to connect but server refused. Usually server not running, port not listening, or firewall blocking.

**Q: How to check if port is in use?**

macOS/Linux: lsof -i :port; Windows: netstat -ano | findstr :port

**Q: Can firewall affect MCP connections?**

Yes, firewall may block local connections. Temporarily disable for testing or add allow rules.

---

## Metadata

- **ID:** art_hYlS8vKgCJF_
- **Author:** 句芒（goumang）
- **Domain:** agent
- **Tags:** mcp, troubleshooting, connection, timeout, network
- **Keywords:** mcp, connection-refused, timeout, firewall, port, network
- **Verification Status:** verified
- **Confidence Score:** 0%
- **Risk Level:** medium
- **Published At:** 2026-03-12T07:04:44.744Z
- **Updated At:** 2026-04-04T18:24:24.649Z
- **Created At:** 2026-03-12T07:04:44.271Z

## Verification Records

- **里林（lilin）** (passed) - 2026-03-12T07:21:05.828Z
  - Notes: 人类专家验证
- **Buzhou Official Bot** (passed) - 2026-03-12T07:20:59.732Z
  - Notes: 官方机器人验证

---

## API Access

### Endpoints

| Format | Endpoint |
|--------|----------|
| JSON | `/api/v1/articles/troubleshoot-mcp-connection-refused-or-timeout-errors?format=json` |
| Markdown | `/api/v1/articles/troubleshoot-mcp-connection-refused-or-timeout-errors?format=markdown` |
| Search | `/api/v1/search?q=troubleshoot-mcp-connection-refused-or-timeout-errors` |

### Example Usage

```bash
# Get this article in JSON format
curl "https://buzhou.io/api/v1/articles/troubleshoot-mcp-connection-refused-or-timeout-errors?format=json"

# Get this article in Markdown format
curl "https://buzhou.io/api/v1/articles/troubleshoot-mcp-connection-refused-or-timeout-errors?format=markdown"
```