openclaw-mcp-bridge

Smart MCP bridge for OpenClaw and other MCP clients.

This project connects multiple MCP servers and exposes them through one interface, with relevance filtering and optional caching.

Built on mcp-use and @modelcontextprotocol/sdk.

Project Status

This package is not published to npm right now. Use it locally by cloning this repository.

Quick Start (Local)

Prerequisites

• Node.js 20.19+ (recommended)
• pnpm
• OpenClaw (only if you want plugin mode)

Clone and Build

git clone https://github.com/gabrielekarra/openclaw-mcp-bridge.git
cd openclaw-mcp-bridge
pnpm install
pnpm build

Usage Modes

1. OpenClaw Plugin (Local)

Install the plugin from the local repository:

openclaw plugins install .
openclaw gateway restart

Enable/configure it in ~/.openclaw/openclaw.json:

{
  "plugins": {
    "entries": {
      "mcp-bridge": {
        "enabled": true,
        "config": {
          "autoDiscover": true
        }
      }
    }
  }
}

Notes:

• Plugin key must be mcp-bridge (matches openclaw.plugin.json).
• With autoDiscover: true, it reads MCP servers from ~/.mcp.json.

2. Standalone MCP Server

Run the bridge server directly:

pnpm start -- --config ./examples/bridge-config.json

You can also run it directly with Node:

node dist/server/index.js --config ./examples/bridge-config.json

For Claude Desktop, add this to claude_desktop_config.json:

{
  "mcpServers": {
    "bridge": {
      "command": "node",
      "args": [
        "/absolute/path/to/openclaw-mcp-bridge/dist/server/index.js",
        "--config",
        "/absolute/path/to/openclaw-mcp-bridge/examples/bridge-config.json"
      ]
    }
  }
}

Operating Modes

The bridge supports two operating modes (both in OpenClaw plugin mode and standalone MCP server mode) controlled by one config key:

{
  "mode": "smart"
}

• smart (default, original design): uses relevance analysis, ranking, thresholds, and optional caching.
• traditional: registers all discovered MCP tools at startup with no relevance filtering or lazy tool activation.

Migration note:

• If you want all MCP tools always visible, use mode: traditional.

Smart mode example (default)

{
  "plugins": {
    "entries": {
      "mcp-bridge": {
        "enabled": true,
        "config": {
          "mode": "smart",
          "autoDiscover": true
        }
      }
    }
  }
}

Traditional mode example

{
  "plugins": {
    "entries": {
      "mcp-bridge": {
        "enabled": true,
        "config": {
          "mode": "traditional",
          "autoDiscover": true
        }
      }
    }
  }
}

Standalone mode examples

examples/bridge-config.json shape:

{
  "mode": "smart",
  "autoDiscover": true
}

{
  "mode": "traditional",
  "autoDiscover": true
}

Registered Tools (Plugin Mode)

Smart mode tools

mcp_find_tools

Finds available tools from connected MCP servers.

Examples:

• "Find tools to create a GitHub issue"
• "What tools are available for Notion?"
• "List all MCP tools"

Behavior:

• If need is present, tools are ranked by relevance.
• If need is empty/missing, it returns available tools (capped for readability).
• Results include server + name values used by mcp_call_tool.

mcp_call_tool

Calls a downstream tool returned by mcp_find_tools.

Required params:

• server (string)
• tool (string)

Optional params:

• arguments (object)

Example call payload:

{
  "server": "notion",
  "tool": "create_page",
  "arguments": {
    "title": "Roadmap"
  }
}

mcp_list_servers

Lists configured MCP servers with discovered tool counts.

Examples:

• "What MCP servers are connected?"
• "Show me available servers"

Traditional mode tools

• Registers every discovered MCP tool at startup.
• Tool names are namespaced as mcp_<server>_<tool>.
• Each registered tool directly calls its underlying MCP server tool.

Standalone behavior summary:

• mode: smart exposes find_tools plus compressed downstream tool entries.
• mode: traditional exposes only namespaced downstream tools (no find_tools meta-tool).

How the Flow Works

1. User asks for a task that likely needs an external tool.
2. Agent calls mcp_find_tools.
3. Bridge discovers tools across MCP servers and ranks matches.
4. Agent calls mcp_call_tool with the selected server + tool.
5. Bridge routes the call to the correct MCP server.

Configuration

Auto-discovery from ~/.mcp.json

When enabled, the bridge imports servers from ~/.mcp.json.

Example:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    },
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/mcp-server"]
    }
  }
}

Explicit server config

You can provide servers explicitly in plugin config:

{
  "plugins": {
    "entries": {
      "mcp-bridge": {
        "enabled": true,
        "config": {
          "autoDiscover": false,
          "servers": [
            {
              "name": "github",
              "transport": "stdio",
              "command": "npx",
              "args": ["-y", "@modelcontextprotocol/server-github"],
              "categories": ["code", "issues", "repos"]
            }
          ]
        }
      }
    }
  }
}

See examples/ for ready-to-use configs.

Standalone note:

• loadConfig() accepts both standalone bridge shape ({ mode, servers, ... }) and OpenClaw plugin shape (plugins.entries["mcp-bridge"].config).

Config Reference

Development

pnpm install
pnpm build
pnpm test
pnpm lint

Troubleshooting

License

MIT

Credits

• OpenClaw — the best personal AI agent
• mcp-use — MCP framework that powers our connections
• Model Context Protocol — the standard that makes this possible