OpenClaw MCP Plugin

Connect your OpenClaw agents to 76+ MCP tools from multiple servers with progressive disclosure — reducing initial token usage by 90%+.

Why Use This?

Without this plugin, connecting to multiple MCP servers loads ALL tools at startup:

• 5 MCP servers × 15 tools each = ~40,000 tokens consumed before you even start

With this plugin using progressive discovery:

• Only 3 meta-tools loaded = ~500 tokens
• Tools load on-demand when you actually need them

Result: 90%+ reduction in initial token usage + cleaner agent context

Quick Start

1. Install the Plugin

# From your openclaw-mcp-plugin directory
npm install
npm run build

# Install into OpenClaw
openclaw plugins install --link /path/to/openclaw-mcp-plugin

2. Create MCP Configuration

Create mcp-config.yaml in one of these locations (checked in order):

| Location | Scope | |----------|-------| | {agentDir}/mcp-config.yaml | Per-agent (e.g. ~/.openclaw/agents/research/agent/mcp-config.yaml) | | {workspaceDir}/mcp-config.yaml | Per-workspace | | pluginConfig.configFilePath | Global fallback |

mcpServers:
  playwright:
    command: playwright-mcp
    args:
      - mcp-serve
      - --mode
      - extension
    config:
      instruction: |
        Playwright browser automation. Use for web browsing, automation, and testing.

  github:
    command: npx
    args:
      - "-y"
      - "@modelcontextprotocol/server-github"
    env:
      GITHUB_TOKEN: "${GITHUB_TOKEN}"

  web-search:
    type: http
    url: "https://api.example.com/mcp"
    headers:
      Authorization: "Bearer ${API_KEY}"

3. Configure OpenClaw

Update your ~/.openclaw/openclaw.json:

{
  "plugins": {
    "entries": {
      "openclaw-mcp": {
        "enabled": true,
        "config": {
          "serverId": "openclaw-mcp"
        }
      }
    }
  },
  "tools": {
    "alsoAllow": ["group:plugins"]
  }
}

4. Restart Gateway

openclaw gateway restart

Usage

The plugin exposes 3 meta-tools that provide progressive access to all MCP capabilities:

Step 1: List Available Tools

{
  "tool": "mcp__list_tools",
  "params": {
    "capability": "browser"
  }
}

Returns tools grouped by server with capability summaries. Optionally filter by capability keyword or serverName.

Step 2: Get Tool Schemas

{
  "tool": "mcp__describe_tools",
  "params": {
    "toolNames": ["browser_navigate", "browser_screenshot"]
  }
}

Returns detailed input schemas, descriptions, and server information for the requested tools.

Step 3: Execute Tools

{
  "tool": "mcp__use_tool",
  "params": {
    "toolName": "browser_navigate",
    "toolArgs": {
      "url": "https://example.com"
    }
  }
}

Per-Agent Configuration

Different agents can connect to different MCP servers by placing mcp-config.yaml in their agent directory:

~/.openclaw/agents/
├── default/agent/mcp-config.yaml    ← default agent's MCP servers
├── research/agent/mcp-config.yaml   ← research agent gets different servers
└── coding/agent/mcp-config.yaml     ← coding agent gets its own set

Agents sharing the same config file reuse the same MCP connections. Agents without a local config fall back to the workspace or global config.

Environment Variables & Secrets

MCP configs reference secrets via ${VAR} syntax. There are two ways to provide them:

Option A: Shell Environment (simplest)

Set env vars in your shell before starting the gateway:

export GITHUB_TOKEN="ghp_abc123"
openclaw gateway start

Option B: OpenClaw Plugin Config (recommended)

Declare secrets in openclaw.json and let OpenClaw's config system resolve them:

{
  "plugins": {
    "entries": {
      "openclaw-mcp": {
        "enabled": true,
        "config": {
          "env": {
            "GITHUB_TOKEN": "${GITHUB_TOKEN}",
            "LINEAR_API_KEY": "${LINEAR_API_KEY}",
            "SLACK_TOKEN": "${SLACK_BOT_TOKEN}"
          }
        }
      }
    }
  }
}

OpenClaw resolves ${VAR} references in config at load time, then the plugin injects them into process.env before MCP servers connect. This works with OpenClaw's env substitution pipeline.

Precedence: Shell env (highest) → pluginConfig.env → one-mcp interpolation.

Existing env vars are never overwritten — your shell environment always takes priority.

Configuration Options

| Option | Default | Description | |--------|---------|-------------| | configFilePath | mcp-config.yaml | Fallback path to MCP configuration file | | serverId | openclaw-mcp | Unique identifier for this MCP instance | | noCache | false | Disable configuration caching | | env | — | Map of env vars to inject before MCP config is read |

How It Works

1. Plugin loads: Registers 3 meta-tools (mcp__list_tools, mcp__describe_tools, mcp__use_tool)
2. Agent invoked: Tool factory resolves per-agent mcp-config.yaml path from ctx.agentDir
3. First tool call: Lazily initializes MCP connections for that agent's config
4. Agent discovers: Calls mcp__list_tools to browse available tools
5. Agent describes: Calls mcp__describe_tools for specific tool schemas
6. Agent executes: Calls mcp__use_tool with the correct arguments

This is the progressive disclosure pattern — tools are discovered on-demand rather than loaded upfront.

Troubleshooting

Plugin not loading?

# Check plugin status
openclaw plugins list

# Check gateway logs
tail -f ~/.openclaw/logs/gateway.log | grep openclaw-mcp

MCP servers not connecting?

# Test your config directly with one-mcp CLI
npx @agiflowai/one-mcp list-tools --config mcp-config.yaml

Tools showing "Method not found" errors?

These are expected for servers that don't support prompts/list. The errors are harmless and don't affect tool functionality.

Env var not being picked up?

Check the resolution order:

1. Is it set in your shell? (echo $VAR_NAME)
2. Is it declared in pluginConfig.env?
3. Does the mcp-config.yaml reference it with ${VAR_NAME} syntax?

Advanced: Skills

You can also add skills (reusable prompt templates) to your MCP config:

mcpServers:
  # ... your servers

skills:
  paths:
    - ~/.openclaw/skills

Skills are discovered through mcp__list_tools and mcp__describe_tools just like MCP tools, using the skill__ prefix.

License

MIT

Credits

Built on @agiflowai/one-mcp — the progressive MCP proxy server.