OpenClaw MCP Registration Runbook

In OpenClaw v2026.2.26 and later, the mcpServers block in openclaw.json is silently ignored. Your agents do not get the tools and no error is thrown. Anyone trying to register a custom MCP server using the documented method will hit this with no diagnostic signal.

The correct path: servers must be registered in /root/.mcporter/mcporter.json via the mcporter registry layer. This requires a Docker volume mount (/root/.mcporter:/root/.mcporter) in your docker-compose.yml. Without it, the file resets on container restart.

Two additional issues covered: Python MCP servers need an initialize handler or OpenClaw will not detect them at startup. Credentials in server configs should use wrapper scripts reading from /root/secrets/ rather than inline environment variables.

What is included: step-by-step setup instructions, a working mcporter.json example, the Docker volume mount addition for docker-compose.yml, a Python MCP server template with the initialize handler, and verification steps to confirm the server is registered and callable.