openclaw-mcp-tool-policy

An OpenClaw plugin that enforces per-MCP-server allow/deny policies on tool calls.

Background

OpenClaw's tools.deny configuration only applies to native built-in tools. MCP server tools exposed via mcp.servers are not covered by this mechanism and cannot be filtered through the standard config — all tools from a connected MCP server are exposed to the agent with no granular control.

This plugin works around that gap using the before_tool_call plugin hook, which fires before every tool call regardless of origin. It inspects the tool name (which OpenClaw materializes as serverName__toolName for MCP tools) and blocks or allows calls based on a per-server policy defined in your openclaw.json.

Related issues:

• Feature: Pre/Post Tool Use Hooks (programmable safety rails)
• [Feature]: MCP Server tool-level allow/deny filtering

Installation

openclaw plugins install openclaw-mcp-tool-policy
openclaw gateway restart

Configuration

Add to your openclaw.json under plugins.entries.mcp-tool-policy.config:

{
  "plugins": {
    "entries": {
      "mcp-tool-policy": {
        "enabled": true,
        "config": {
          "servers": {
            "mcp1": {
              "tools": [
                "delete_operation"
              ]
            },
            "mcp2": {
              "mode": "allow",
              "tools": [
                "read_operation",
                "list_operation"
              ]
            }
          },
          "log": true
        }
      }
    }
  }
}

The server name must match exactly the key you used in mcp.servers. OpenClaw exposes MCP tool calls as serverName__toolName internally — this plugin splits on __ to extract both parts and apply the matching server policy.

Servers not listed in config.servers are not affected. Native OpenClaw tools (those without a __ prefix) are also not affected.

Modes

deny — All tools from this server are allowed by default. Tools listed in tools are blocked.

allow — All tools from this server are blocked by default. Only tools listed in tools are permitted.

Logging

When log: true is set, every decision is written to the gateway log via api.logger.info.

How it works

OpenClaw materializes MCP tool names as serverName__toolName when registering tools from mcp.servers. The before_tool_call plugin hook receives this full name before execution. This plugin splits on __, looks up the server policy, and returns { block: true } when the policy is violated. Blocked tool calls never reach the MCP server.

Native tools and tools from servers with no configured policy are passed through unchanged.

License

MIT