Delx
OpenClaw / Fix: MCP Registry Connection Error

Fix: Could Not Connect to MCP Server mcp-registry

If you are seeing could not connect to MCP server mcp-registry in Claude Code or Claude Desktop, the MCP registry server is unreachable. This page walks through every possible cause and gives you exact commands to diagnose and fix the issue in under five minutes.

What the error means

The MCP registry is a lightweight server that acts as a central directory for all your MCP tool servers. When Claude Code or Claude Desktop starts a session, it queries the registry to discover which MCP servers are available and how to connect to them. If the registry itself is unreachable, the client cannot discover any tools and throws this connection error.

Common variations of this error include:

Quick fix checklist

Run through these five checks in order. Most issues are resolved by step 2 or 3.

  1. Is mcp-registry running? Check with ps aux | grep mcp-registry or look for the process in your task manager.
  2. Is the config file pointing to the right address? Open your MCP config and verify the host and port match where the registry is actually listening.
  3. Is something else using the port? Run lsof -i :3100 (replace 3100 with your configured port) to check for conflicts.
  4. Is your auth token valid? If the registry requires authentication, confirm the token has not expired or been rotated.
  5. Can you reach the registry manually? Test with curl http://localhost:3100/health to confirm basic connectivity.

Step 1: Check if mcp-registry is running

The most common cause is simply that the registry server is not running. Start it manually and verify it responds:

# Start the mcp-registry server
npx @anthropic/mcp-registry

# In a separate terminal, verify it is alive
curl -s http://localhost:3100/health
# Expected: {"status":"ok"}

# Check if the process is running
ps aux | grep mcp-registry
# You should see a node process listening on port 3100

If npx @anthropic/mcp-registry fails with a package-not-found error, install it explicitly first:

npm install -g @anthropic/mcp-registry
mcp-registry

If the registry starts but immediately exits, check the output for error messages. Common issues are missing dependencies, unsupported Node versions (requires Node 18+), or a corrupted package installation.

Step 2: Verify your config file

The config file tells your Claude client where to find the registry. The file location depends on which client you are using:

Open the file and confirm the mcp-registry entry exists and has the correct connection details:

// ~/.claude/mcp_servers.json (Claude Code)
{
  "mcpServers": {
    "mcp-registry": {
      "command": "npx",
      "args": ["@anthropic/mcp-registry"],
      "env": {}
    }
  }
}

// Or if using a remote/already-running registry:
{
  "mcpServers": {
    "mcp-registry": {
      "url": "http://localhost:3100",
      "transport": "sse"
    }
  }
}

Watch for these common config mistakes:

Step 3: Fix network and port conflicts

If the registry process is running and the config looks correct, the issue is likely a port conflict or firewall rule blocking the connection.

# Check what is using port 3100 (macOS/Linux)
lsof -i :3100

# Check what is using port 3100 (Windows PowerShell)
netstat -ano | findstr :3100

# If another process is using the port, either:
# 1. Kill the conflicting process
kill -9 <PID>

# 2. Or start mcp-registry on a different port
MCP_REGISTRY_PORT=3200 npx @anthropic/mcp-registry
# Then update your config file to match the new port

Firewall and VPN considerations:

Step 4: Fix auth token problems

If your mcp-registry is configured to require authentication, an expired or missing token will cause connection failures that look identical to network errors.

# Test authentication manually
curl -s -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:3100/health

# If you get a 401 or 403, the token is invalid

# Regenerate or rotate the token
npx @anthropic/mcp-registry token refresh

# Update the token in your config
{
  "mcpServers": {
    "mcp-registry": {
      "url": "http://localhost:3100",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer NEW_TOKEN_HERE"
      }
    }
  }
}

If you are not sure whether auth is required, check the registry startup logs. It will print a message like Auth enabled: token required for all connections when authentication is active. For local development, you can often disable auth entirely by removing the token configuration from the registry startup.

Step 5: Reinstall and reset mcp-registry

If none of the above steps work, a clean reinstall often resolves corrupted state or dependency issues:

# Remove the existing installation
npm uninstall -g @anthropic/mcp-registry

# Clear the npm cache
npm cache clean --force

# Clear any cached npx packages
rm -rf ~/.npm/_npx

# Reinstall from scratch
npm install -g @anthropic/mcp-registry

# Verify the installation
mcp-registry --version

# Start the registry and test
mcp-registry
curl -s http://localhost:3100/health

If you previously had a working setup that broke after a Node.js or npm upgrade, make sure your Node version is still compatible. The MCP registry requires Node 18 or later:

# Check your Node version
node --version
# Must be v18.0.0 or higher

# If using nvm, switch to a compatible version
nvm use 20
npm install -g @anthropic/mcp-registry

Alternative: Configure MCP servers without the registry

If you cannot get mcp-registry working or simply do not need a centralized registry, you can configure each MCP server directly in your config file. This bypasses the registry entirely and connects to each server individually.

// ~/.claude/mcp_servers.json — direct server config (no registry)
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://user:pass@localhost:5432/mydb"
      }
    }
  }
}

With this approach, each server is managed independently. You lose the centralized discovery that the registry provides, but you gain simplicity and eliminate the registry as a single point of failure. For most individual developers, this direct configuration is perfectly adequate. The registry becomes more valuable when you have a team sharing a common set of MCP servers or when you need dynamic server discovery.

Monitoring MCP server health with Delx

Once you have your MCP servers running reliably, you can use Delx agent operations tools to continuously monitor their health and catch connection issues before they disrupt your workflows.

# Use the Delx A2A endpoint to check MCP server status
curl -s https://api.delx.ai/v1/a2a \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [{"type": "text", "text": "check mcp health"}]
      }
    },
    "id": 1
  }'

Delx heartbeat patterns are especially useful here. By setting up a cron-based heartbeat that pings each MCP server at regular intervals, you can detect outages within minutes and trigger automated recovery before your agents notice any disruption. This transforms MCP server management from reactive firefighting into proactive operations.

For production deployments where MCP server uptime is critical, consider combining Delx telemetry with the OpenClaw session recovery pattern: if an MCP server goes down, the agent automatically falls back to cached tool definitions and queues operations until the server is restored.

Related

Back to OpenClaw hubOpenClaw best practices