Why does OpenClaw fail to connect to my MCP server?

Most MCP connection failures come from the server process not starting (spawn error), a wrong command path, or a port conflict. Check that your MCP server binary is installed and executable from the same PATH that OpenClaw uses.

How do I check if my MCP server is running?

For stdio-based servers, OpenClaw spawns the process. Check openclaw logs --follow for spawn errors. For HTTP/SSE servers, verify the server is listening with: curl http://localhost: /sse

What does "MCP protocol version mismatch" mean?

Your MCP server is using a different protocol version than OpenClaw expects. Update either the server or OpenClaw to matching versions.

Can I use Claude Desktop MCP servers with OpenClaw?

Yes. If a server works in Claude Desktop, it should work in OpenClaw too. Copy the server config from your claude_desktop_config.json into your OpenClaw skill config.

Fix OpenClaw MCP Server Errors

MCP Server Failed to Connect

OpenClaw uses the Model Context Protocol (MCP) to connect agents to external tools. When an MCP server fails to start or connect, agents lose access to those tools entirely. The fix depends on whether it is a spawn, network, or protocol error.

MCP server errors in OpenClaw fall into three categories: the server process fails to start (spawn errors), the server starts but cannot be reached (connection errors), or the server connects but speaks a different protocol version (version mismatch).

Next Step

Fix now, then reduce repeat incidents

If this issue keeps coming back, validate your setup in Doctor first, then harden your config.

Open Doctor Harden Config

Jump to Fix

Spawn / ENOENT errors Connection refused Tool call timeout Protocol version mismatch Claude Desktop MCP servers Debug MCP logs

What the Errors Look Like

Error: spawn npx ENOENT — MCP server failed to start

MCP server "my-server" failed: connection refused on port 3001

tool call timed out after 30000ms (MCP server not responding)

MCP protocol version mismatch: server=2024-11-05, client=2025-03-26

Error: MCP server process exited with code 1 before initialization

Failed to connect to MCP server: getaddrinfo ENOTFOUND localhost

Spawn / ENOENT Errors

stdio-based MCP servers are started by OpenClaw as child processes. If the command is not found, you get a spawn ENOENT error.

Diagnose spawn errors

# Check if the MCP server binary is installed
which npx          # for npx-based servers
which uvx           # for Python uv-based servers
which node          # for Node-based servers

# Test the server command directly
npx -y @modelcontextprotocol/server-filesystem /tmp

# Check PATH used by OpenClaw
openclaw config get system.env.PATH

Common fix: set full binary path

OpenClaw's PATH may differ from your shell's. Use absolute paths in your MCP server config:

# Instead of: command: "npx"

# Use absolute path: command: "/usr/local/bin/npx"

Connection Refused (HTTP/SSE Servers)

For HTTP or SSE-based MCP servers, OpenClaw connects to a running process over a port. "Connection refused" means the server is not running or is on the wrong port.

Check server is running

# Test SSE endpoint
curl http://localhost:3001/sse

# Check what is listening on the port
lsof -i :3001       # macOS/Linux
netstat -ano | findstr 3001   # Windows

# Start the MCP server manually to see errors
npx @modelcontextprotocol/server-filesystem /tmp

Tool Call Timeout

If the MCP server connects but tool calls time out, the server is running but responding too slowly or hanging.

Increase MCP timeout

# Increase tool call timeout (default: 30s)
openclaw config set mcp.toolCallTimeout 60000

# Restart and test
openclaw gateway restart

Server performing slow operations

Database queries, file system operations, or network calls inside the MCP server may exceed the default 30s timeout. Increase timeout or optimize the server.

Server process is hanging

The MCP server process may be deadlocked. Check server logs and restart it. Look for infinite loops or blocking I/O.

Large response payloads

MCP tool responses over ~1MB can cause timeouts. Paginate results or truncate large outputs in your MCP server.

Protocol Version Mismatch

MCP is an evolving protocol. If your server was built for an older version, you may see version mismatch errors.

Check and update

# Update OpenClaw to latest
npm update -g openclaw

# Update npx-based MCP servers (they auto-update on next run)
npx -y @modelcontextprotocol/server-filesystem --version

# For npm-installed servers
npm update -g @modelcontextprotocol/server-filesystem

Using Claude Desktop MCP Servers with OpenClaw

MCP servers configured in Claude Desktop can be reused in OpenClaw. Find your Claude Desktop config:

Find Claude Desktop config

# macOS
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Windows
type %APPDATA%\Claude\claude_desktop_config.json

# Linux
cat ~/.config/Claude/claude_desktop_config.json

Copy the mcpServers entries into your OpenClaw skill config. The format is compatible.

Enable MCP Debug Logging

Enable MCP debug logs

# Enable verbose MCP logging
openclaw config set log.level debug
openclaw config set mcp.debug true
openclaw gateway restart

# Tail logs to see MCP messages
openclaw logs --follow | grep -i mcp

Still Not Working?

Run the Doctor

npx clawkit-doctor@latest

Or use the web Error Doctor — paste your MCP error for instant diagnosis.

Related Errors

MCP errors often appear alongside these: