openclaw - 💡(How to fix) Fix [Feature]: MCP tool namespace isolation to prevent cross-server name collisions [1 participants]

Summary

Problem When multiple MCP servers are configured in openclaw.json, tools from different servers that share the same name cause a silent collision. The second tool is skipped with a warning: WARN: skipped tool "list_services" from server "opentelemetry-mcp" because the name already exists. Currently, OpenClaw registers all MCP tools into a flat global namespace. When two servers expose a tool with the same name, the first one wins and the second is silently dropped. This means users lose access to functionality from the second server with no error — only a warning log. Real-world scenario We run two observability MCP servers simultaneously because our stack uses different tracing backends for different languages: { "mcpServers": { "skywalking-mcp": { "command": "/path/to/swmcp" }, "opentelemetry-mcp": { "command": "/path/to/opentelemetry-mcp" } } } skywalking-mcp — for Java services (SkyWalking backend) opentelemetry-mcp — for Golang services (OpenTelemetry backend) Both servers expose list_services, list_traces, get_trace_detail, etc. — which are standard operations for any tracing tool. The collision means we can only query one backend, defeating the purpose of having both configured. This is not unique to observability tools. As the MCP ecosystem grows, name collisions across independent servers will become increasingly common (e.g., multiple database MCP servers all exposing query, list_tables; multiple cloud provider MCPs all exposing list_instances, etc.). Current workaround Using toolPrefix to manually namespace one of the servers: "opentelemetry-mcp": { "command": "/path/to/opentelemetry-mcp", "toolPrefix": "otel_" } This works but is manual, fragile, and the user has to know about the collision in advance.

Problem to solve

Option A (preferred): Automatic server-scoped namespacing Register tools internally as {serverName}.{toolName} (or {serverName}_{toolName}), so the model sees: skywalking_mcp_list_services opentelemetry_mcp_list_services This could be opt-in via a global config flag: { "mcpServers": { "_options": { "autoNamespace": true } } } Option B: Per-server namespace with explicit opt-in Add a namespace field per server: "opentelemetry-mcp": { "command": "...", "namespace": "otel" } Tools become otel_list_services, otel_list_traces, etc. Option C (minimal): Warn + suggest fix Keep the current flat namespace, but improve the warning message to suggest using toolPrefix: WARN: skipped tool "list_services" from server "opentelemetry-mcp" because it conflicts with the same tool from "skywalking-mcp". Add "toolPrefix" to one of the servers to resolve.

Proposed solution

Option A (preferred): Automatic server-scoped namespacing Register tools internally as {serverName}.{toolName} (or {serverName}_{toolName}), so the model sees: skywalking_mcp_list_services opentelemetry_mcp_list_services This could be opt-in via a global config flag: { "mcpServers": { "_options": { "autoNamespace": true } } } Option B: Per-server namespace with explicit opt-in Add a namespace field per server: "opentelemetry-mcp": { "command": "...", "namespace": "otel" } Tools become otel_list_services, otel_list_traces, etc. Option C (minimal): Warn + suggest fix Keep the current flat namespace, but improve the warning message to suggest using toolPrefix: WARN: skipped tool "list_services" from server "opentelemetry-mcp" because it conflicts with the same tool from "skywalking-mcp". Add "toolPrefix" to one of the servers to resolve.

Alternatives considered

Option A (preferred): Automatic server-scoped namespacing Register tools internally as {serverName}.{toolName} (or {serverName}_{toolName}), so the model sees: skywalking_mcp_list_services opentelemetry_mcp_list_services This could be opt-in via a global config flag: { "mcpServers": { "_options": { "autoNamespace": true } } } Option B: Per-server namespace with explicit opt-in Add a namespace field per server: "opentelemetry-mcp": { "command": "...", "namespace": "otel" } Tools become otel_list_services, otel_list_traces, etc. Option C (minimal): Warn + suggest fix Keep the current flat namespace, but improve the warning message to suggest using toolPrefix: WARN: skipped tool "list_services" from server "opentelemetry-mcp" because it conflicts with the same tool from "skywalking-mcp". Add "toolPrefix" to one of the servers to resolve.

Impact

OpenClaw version: 2026.3.23-2 OS: macOS (headless, SSH) MCP servers: skywalking-mcp + opentelemetry-mcp (both expose list_services)

Evidence/examples

No response

Additional information

The MCP protocol itself identifies servers by name, so the namespace information already exists at the transport level. The collision only happens because OpenClaw flattens tools into a single registry during loading. This will become a more common issue as users adopt multiple MCP servers from the growing ecosystem — especially servers in the same domain (databases, cloud providers, observability, CI/CD, etc.) that naturally use similar tool names.