MCP Server Connection Failure – 2025-10-29

Incident Summary

Date: October 29, 2025
Severity: Medium
Status: ✅ RESOLVED
Component: MCP_DOCKER (Obsidian MCP Server)
Resolution Time: < 30 minutes

Symptoms

• Unable to connect to Obsidian MCP server
• Connection refused errors on host.docker.internal:27124
• Error code: [Errno 111] Connection refused
• All MCP_DOCKER tool calls failing with HTTPSConnectionPool errors

Root Cause ✓ CONFIRMED

Root Cause: Obsidian application was not running on the host system.

The MCP server for Obsidian requires the Obsidian desktop application to be actively running. When the application is closed, the MCP server stops accepting connections, resulting in “Connection refused” errors.

Technology Stack & Architecture

System Architecture

graph TB
    subgraph "Layer 0: Container Runtime"
        A[Docker Desktop]
    end

    subgraph "Layer 1: MCP Server"
        B[Obsidian Application]
        C[Obsidian MCP Server]
        D[API Key Authentication]
    end

    subgraph "Layer 2: MCP Client"
        E[Claude Desktop Client]
        F[MCP Gateway]
    end

    subgraph "User Interface"
        G[Claude Chat Interface]
    end

    A -->|Hosts| C
    B -->|Provides| C
    B -->|Required for| C
    C -->|Authenticates via| D
    C -->|Port 27124| F
    F -->|Connects to| E
    E -->|Powers| G
    G -->|User interaction| E

    style B fill:#ff6b6b,stroke:#c92a2a,stroke-width:3px
    style C fill:#fab005,stroke:#f59f00,stroke-width:2px
    style E fill:#51cf66,stroke:#2f9e44,stroke-width:2px

    classDef critical fill:#ff6b6b,stroke:#c92a2a
    classDef warning fill:#fab005,stroke:#f59f00
    classDef normal fill:#51cf66,stroke:#2f9e44

graph TB
    subgraph "Layer 0: Container Runtime"
        A[Docker Desktop]
    end

    subgraph "Layer 1: MCP Server"
        B[Obsidian Application]
        C[Obsidian MCP Server]
        D[API Key Authentication]
    end

    subgraph "Layer 2: MCP Client"
        E[Claude Desktop Client]
        F[MCP Gateway]
    end

    subgraph "User Interface"
        G[Claude Chat Interface]
    end

    A -->|Hosts| C
    B -->|Provides| C
    B -->|Required for| C
    C -->|Authenticates via| D
    C -->|Port 27124| F
    F -->|Connects to| E
    E -->|Powers| G
    G -->|User interaction| E

    style B fill:#ff6b6b,stroke:#c92a2a,stroke-width:3px
    style C fill:#fab005,stroke:#f59f00,stroke-width:2px
    style E fill:#51cf66,stroke:#2f9e44,stroke-width:2px

    classDef critical fill:#ff6b6b,stroke:#c92a2a
    classDef warning fill:#fab005,stroke:#f59f00
    classDef normal fill:#51cf66,stroke:#2f9e44

Component Dependencies

Critical Discovery: Obsidian Application must be running (highlighted in red) – this dependency was not clearly documented in any interface.

User Journey & Troubleshooting Timeline

User Steps Taken

1. Opened Claude chat and received error: “Obsidian MCP Server Failed”
2. Searched Claude interface for error indicators – no helpful information found
3. Reviewed Claude logs using PowerShell commands:

   Get-Content "C:\Users\win10\AppData\Roaming\Claude\logs\*.log" | 
   Select-String -Pattern "error|failed|exception|MCP" -Context 2,2 | 
   Select-Object -Last 50

4. Verified Docker Desktop – Updated to latest version
5. Checked Docker Desktop MCP Server configuration for Obsidian
6. Verified Docker Desktop MCP Client configuration for Claude
7. Ran diagnostic commands (detailed below)
8. Inferred solution from key indicators during troubleshooting

Gap Analysis

Key Finding: Neither Docker Desktop nor Claude interface indicated that the Obsidian application needed to be running. Resolution was obtained by an experienced engineer inferring the direction from key indicators presented during troubleshooting steps.

Missing Indicators:

• No warning in Claude UI about MCP server dependencies
• No status indicator showing Obsidian app state
• No helpful error message explaining the actual cause
• Docker Desktop showed MCP configuration as valid despite Obsidian not running

Detailed Troubleshooting Steps

Initial Investigation

Step 1: List Available MCP Servers

docker mcp server ls

Output:

desktop-commander
duckduckgo
fetch
obsidian

Finding: All expected MCP servers were configured, including the obsidian server.

Step 2: Test Gateway Configuration

docker mcp gateway run --verbose --dry-run

Finding: Gateway configuration appeared valid in dry-run mode.

Step 3: List Available MCP Tools

docker mcp tools list --verbose

Finding: Tools were listed but connection status unclear.

Step 4: Inspect Obsidian Server Configuration

docker mcp server inspect obsidian

Finding: Server configuration was present and appeared correct.

Step 5: Test Direct Connection – BEFORE FIX

curl http://localhost:27124/health

Output:

curl: (7) Failed to connect to localhost port 27124: Connection refused

Critical Finding: Port 27124 was not accepting connections at all. This indicated the server process was not listening on the port, not just refusing authentication or returning errors.

Analysis: “Connection refused” (error 7) means:

• No process is listening on port 27124
• The TCP connection attempt was actively rejected by the OS
• This is different from timeout (no response) or HTTP errors (server responding with error codes)

Root Cause Identified

After the diagnostic steps above, the hypothesis was formed: If the MCP server configuration exists but nothing is listening on the port, the Obsidian application itself must not be running.

Solution Applied

Action: Started the Obsidian desktop application.

Step 6: Re-test Connection – AFTER FIX

curl http://localhost:27124/health

Output:

curl: (52) Empty reply from server

Analysis: The error changed from (7) to (52):

• Error 7: Connection refused – nothing listening
• Error 52: Empty reply from server – server is now listening but returned no data

This confirmed the fix was successful. The “empty reply” is expected behavior for this endpoint – the important change is that the server is now accepting connections.

Verification: MCP operations through Claude interface were tested and confirmed working.

Key Diagnostic Insight

The progression of curl errors provided the critical clue:

1. Before fix: Error 7 (Connection refused) = No server process
2. After fix: Error 52 (Empty reply) = Server running but endpoint returns no body
3. Conclusion: Starting Obsidian brought the MCP server online

Why This Happened

The error message host.docker.internal:27124 indicated a Docker-based issue, but the actual problem was simpler:

• The Obsidian application serves as the MCP server host
• When Obsidian is closed, the MCP endpoint becomes unavailable
• The connection attempts fail with “Connection refused” rather than “Connection timeout”

Solution ✓ IMPLEMENTED

Solution: Start the Obsidian application.

Steps Taken

1. Launched Obsidian desktop application
2. Verified vault was accessible
3. Confirmed MCP server connection restored
4. All MCP_DOCKER operations resumed successfully

Verification

✓ obsidian_list_files_in_vault - Working
✓ Connection to host.docker.internal:27124 - Established
✓ Vault access - Confirmed

Log Analysis

PowerShell Commands Used

# Search for errors in Claude logs
Get-Content "C:\Users\win10\AppData\Roaming\Claude\logs\*.log" | 
Select-String -Pattern "error|failed|exception|MCP" -Context 2,2 | 
Select-Object -Last 50

Errors Found in Claude Logs

Location: C:\Users\win10\AppData\Roaming\Claude\logs\

Errors from 2025-10-08 (unrelated to this incident):

• Multiple ResizeObserver loop completed with undelivered notifications errors (UI-related, benign)
• WebGL deprecation warnings (not critical)
• Note: No specific MCP connection logs found, suggesting Claude logs may not capture MCP server connection attempts

Prevention Strategies

1. User Awareness

• [ ] Document that Obsidian must be running for MCP integration
• [ ] Add reminder to startup procedures
• [ ] Consider adding Obsidian to Windows startup applications (optional)

2. Better Error Messages

• [ ] Request improved error messaging that indicates “Obsidian not running” vs generic connection failure
• [ ] Add troubleshooting hints in Claude interface for MCP failures
• [ ] Display MCP server status in Claude UI

3. Monitoring & Notifications

• [ ] Create a simple health check script to verify Obsidian is running
• [ ] Set up Windows Task Scheduler to auto-start Obsidian (if desired)
• [ ] Implement visual indicator in Docker Desktop for application dependencies

4. Documentation

• [ ] Create troubleshooting guide for MCP connection issues
• [ ] Document dependency: Claude MCP → Obsidian Application
• [ ] Add to knowledge base
• [ ] Update Docker Desktop documentation about application requirements

5. Startup Checklist

Create a daily startup checklist:

[ ] Start Obsidian application
[ ] Verify vault is loaded
[ ] Test Claude MCP connection (optional)

Recommended Configuration

Option 1: Auto-start Obsidian (Windows)

1. Press Win + R, type shell:startup
2. Create shortcut to Obsidian.exe in the startup folder
3. Obsidian will launch automatically on system boot

Option 2: Manual Start with Reminder

• Add Obsidian to taskbar for quick access
• Create a note in daily template reminding to start Obsidian

Option 3: Verification Script

Create a PowerShell script to check if Obsidian is running:

# check-obsidian.ps1
$process = Get-Process -Name "Obsidian" -ErrorAction SilentlyContinue
if ($null -eq $process) {
    Write-Host "⚠️ Obsidian is not running. MCP server unavailable." -ForegroundColor Yellow
    Write-Host "Start Obsidian to enable Claude MCP integration." -ForegroundColor Cyan
} else {
    Write-Host "✓ Obsidian is running. MCP server available." -ForegroundColor Green
}

Option 4: Quick Diagnostics Command Reference

For future troubleshooting, use this command sequence:

# Check MCP server configuration
docker mcp server ls

# Test connection
curl http://localhost:27124/health

# If error 7 (Connection refused):
# → Start Obsidian application

# If error 52 (Empty reply):
# → Server is running correctly

Lessons Learned

What Went Well

• Systematic troubleshooting approach led to quick resolution
• Docker MCP commands were helpful in ruling out configuration issues
• Simple solution with immediate resolution
• No data loss or system corruption
• curl testing provided clear before/after confirmation
• Experienced engineer able to infer solution from indicators

What Could Be Improved

• Initial troubleshooting assumed Docker/container issue
• Could have checked for running processes first
• Better documentation of dependencies needed
• Error messages could be more descriptive about the actual cause
• No UI indicators in Claude or Docker Desktop about application state
• Documentation gap – dependency not clearly stated

Key Takeaway

Always verify the basics first: Before diving into complex Docker/network debugging, check if the required application is simply not running. The curl error codes (7 vs 52) were the smoking gun that led to the solution.

UX Improvement Needed: System should provide clear indicators when dependent applications are not running, rather than relying on user inference from technical diagnostics.

Impact Assessment

• Data Loss: None
• Downtime: ~30 minutes of MCP functionality unavailable
• User Impact: Unable to access Obsidian vault via Claude
• System Impact: None – isolated to MCP integration
• User Experience: Poor – required expert troubleshooting skills to resolve

Troubleshooting Workflow for Future Reference

graph TD
    A[MCP Connection Error] --> B{Check MCP Config}
    B -->|OK| C[Test with curl]
    C -->|Error 7| D[Check if Obsidian Running]
    C -->|Error 52| E[Normal - Server OK]
    C -->|Other Error| F[Check Logs]
    D -->|Not Running| G[Start Obsidian]
    D -->|Running| H[Check Port Binding]
    G --> I[Verify with curl]
    I -->|Error 52| J[Success!]
    I -->|Still Error 7| H

graph TD
    A[MCP Connection Error] --> B{Check MCP Config}
    B -->|OK| C[Test with curl]
    C -->|Error 7| D[Check if Obsidian Running]
    C -->|Error 52| E[Normal - Server OK]
    C -->|Other Error| F[Check Logs]
    D -->|Not Running| G[Start Obsidian]
    D -->|Running| H[Check Port Binding]
    G --> I[Verify with curl]
    I -->|Error 52| J[Success!]
    I -->|Still Error 7| H

Next Steps

• [x] Start Obsidian application
• [x] Verify MCP connection restored
• [x] Document incident and solution with detailed troubleshooting
• [ ] Implement prevention strategy (choose from options above)
• [ ] Add to troubleshooting knowledge base
• [ ] Consider auto-start configuration
• [ ] Submit feedback to Anthropic about UX improvements needed

Related Documentation

• MCP Server Architecture
• Obsidian Integration Setup
• Docker MCP Commands Reference

Update Log

• 2025-10-29 10:00 AM: Initial incident detected – MCP connection failures
• 2025-10-29 10:02 AM: Searched Claude interface – no helpful indicators
• 2025-10-29 10:03 AM: Reviewed Claude logs with PowerShell – no MCP errors found
• 2025-10-29 10:04 AM: Verified Docker Desktop updated to latest version
• 2025-10-29 10:05 AM: Checked Docker Desktop MCP Server configuration – valid
• 2025-10-29 10:06 AM: Verified Docker Desktop MCP Client configuration – valid
• 2025-10-29 10:07 AM: Ran docker mcp diagnostics – configuration valid
• 2025-10-29 10:10 AM: Tested with curl – Connection refused (Error 7)
• 2025-10-29 10:15 AM: Root cause inferred – Obsidian not running
• 2025-10-29 10:20 AM: Solution applied – Started Obsidian application
• 2025-10-29 10:22 AM: Re-tested with curl – Empty reply (Error 52) = Success
• 2025-10-29 10:25 AM: Verified resolution – All systems operational
• 2025-10-29 10:45 AM: Complete incident report with architecture diagrams published to vault

Status: ✅ RESOLVED
Tags: #incident #mcp #obsidian #troubleshooting #resolved #connection-failure #docker #curl #architecture #user-experience
Priority: Low (for future prevention) / Medium (for UX improvements)