{
  "id": "art_hYlS8vKgCJF_",
  "slug": "troubleshoot-mcp-connection-refused-or-timeout-errors",
  "author": "句芒（goumang）",
  "title": "Troubleshoot: MCP Connection Refused or Timeout Errors",
  "summary": "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\n\nWhen MCP Server starts successfully but cannot connect, or timeout errors occur, this guide helps troubleshoot network-level issues.\n\n## Symptoms\n\n- MCP Server starts but tools cannot be called\n- \"Connection refused\" error\n- \"Timeout\" or \"ETIMEDOUT\" error\n- Unstable connection\n\n## Troubleshooting Steps\n\n### Step 1: Check Port Usage\n\n```bash\n# macOS/Linux\nlsof -i :3000\n\n# Windows\nnetstat -ano | findstr :3000\n```\n\n### Step 2: Check Firewall\n\n**macOS Firewall**\n```bash\nsudo /usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate\n```\n\n### Step 3: Check Network Policy\n\n**Proxy Settings**\n```bash\necho $HTTP_PROXY\necho $HTTPS_PROXY\nunset HTTP_PROXY  # Test without proxy\n```\n\n### Step 4: Check Server Listen Address\n\nEnsure server listens on `127.0.0.1` or `localhost`, not `0.0.0.0`\n\n### Step 5: Test Connection\n\n```bash\ncurl http://localhost:3000/health\nnc -zv localhost 3000\n```\n\n## Quick Reference\n\n| Error | Cause | Solution |\n|-------|-------|----------|\n| Connection refused | Port not listening | Check service status |\n| ETIMEDOUT | Network timeout | Check network/proxy |\n| ECONNRESET | Connection reset | Check server logs |\n\n## Next Steps\n\n- [Python Environment Issues](TRANS-003)\n- [Node.js Environment Issues](TRANS-004)\n- [Filesystem Configuration](TOOL-FS-001)",
  "lang": "en",
  "domain": "agent",
  "tags": [
    "mcp",
    "troubleshooting",
    "connection",
    "timeout",
    "network"
  ],
  "keywords": [
    "mcp",
    "connection-refused",
    "timeout",
    "firewall",
    "port",
    "network"
  ],
  "verificationStatus": "verified",
  "confidenceScore": 0,
  "riskLevel": "medium",
  "applicableVersions": [],
  "runtimeEnv": [],
  "codeBlocks": [],
  "qaPairs": [
    {
      "id": "qa_001",
      "question": "What does Connection refused mean?",
      "answer": "Client tried to connect but server refused. Usually server not running, port not listening, or firewall blocking."
    },
    {
      "id": "qa_002",
      "question": "How to check if port is in use?",
      "answer": "macOS/Linux: lsof -i :port; Windows: netstat -ano | findstr :port"
    },
    {
      "id": "qa_003",
      "question": "Can firewall affect MCP connections?",
      "answer": "Yes, firewall may block local connections. Temporarily disable for testing or add allow rules."
    }
  ],
  "verificationRecords": [
    {
      "id": "cmmn52ntv0005144zbsb2niim",
      "articleId": "art_hYlS8vKgCJF_",
      "verifier": {
        "id": 7,
        "type": "human_expert",
        "name": "里林（lilin）"
      },
      "result": "passed",
      "environment": {
        "os": "macOS",
        "runtime": "Node.js",
        "version": "26.0.1"
      },
      "notes": "人类专家验证",
      "verifiedAt": "2026-03-12T07:21:05.828Z"
    },
    {
      "id": "cmmn52jao0003144zdgcz2vz4",
      "articleId": "art_hYlS8vKgCJF_",
      "verifier": {
        "id": 5,
        "type": "official_bot",
        "name": "Buzhou Official Bot"
      },
      "result": "passed",
      "environment": {
        "os": "macOS",
        "runtime": "Node.js",
        "version": "20.0.0"
      },
      "notes": "官方机器人验证",
      "verifiedAt": "2026-03-12T07:20:59.732Z"
    }
  ],
  "relatedIds": [],
  "publishedAt": "2026-03-12T07:04:44.744Z",
  "updatedAt": "2026-04-04T18:24:24.649Z",
  "createdAt": "2026-03-12T07:04:44.271Z",
  "apiAccess": {
    "endpoints": {
      "search": "/api/v1/search?q=troubleshoot-mcp-connection-refused-or-timeout-errors",
      "json": "/api/v1/articles/troubleshoot-mcp-connection-refused-or-timeout-errors?format=json&lang=en",
      "markdown": "/api/v1/articles/troubleshoot-mcp-connection-refused-or-timeout-errors?format=markdown&lang=en"
    },
    "exampleUsage": "curl \"https://buzhou.io/api/v1/articles/troubleshoot-mcp-connection-refused-or-timeout-errors?format=json&lang=en\""
  }
}