@aiwerk/mcp-bridge

Multiplex multiple MCP servers into one interface. One config, one connection, all your tools.

Works with Claude Desktop, Cursor, Windsurf, Cline, OpenClaw, or any MCP client.

Why?

Most AI agents connect to MCP servers one-by-one. With 10+ servers, that's 10+ connections, 200+ tools in context, and thousands of wasted tokens.

MCP Bridge solves this:

• Router mode: all servers behind one mcp meta-tool (~99% token reduction)
• Direct mode: all tools registered individually with automatic prefixing
• 3 transports: stdio, SSE, streamable-http
• Built-in catalog: install popular servers with one command
• Zero config secrets in files: ${ENV_VAR} resolution from .env

Install

npm install -g @aiwerk/mcp-bridge

Quick Start

# 1. Initialize config
mcp-bridge init

# 2. Install a server from the catalog
mcp-bridge install todoist

# 3. Add your API key
echo "TODOIST_API_TOKEN=your-token" >> ~/.mcp-bridge/.env

# 4. Start (stdio mode — connects to any MCP client)
mcp-bridge

Use with Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "bridge": {
      "command": "mcp-bridge",
      "args": []
    }
  }
}

Use with Cursor / Windsurf

Add to your MCP config:

{
  "mcpServers": {
    "bridge": {
      "command": "mcp-bridge",
      "args": ["--config", "/path/to/config.json"]
    }
  }
}

Use with OpenClaw

Install as a plugin (handles everything automatically):

openclaw plugins install @aiwerk/openclaw-mcp-bridge

⚠️ Important: Always use the full scoped name @aiwerk/openclaw-mcp-bridge. The unscoped openclaw-mcp-bridge on npm is a different, unrelated package.

See @aiwerk/openclaw-mcp-bridge for details.

Configuration

Config: ~/.mcp-bridge/config.json | Secrets: ~/.mcp-bridge/.env

{
  "mode": "router",
  "servers": {
    "todoist": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@doist/todoist-ai"],
      "env": { "TODOIST_API_KEY": "${TODOIST_API_TOKEN}" },
      "description": "Task management"
    },
    "github": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" },
      "description": "GitHub repos, issues, PRs"
    },
    "notion": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-notion"],
      "env": { "NOTION_API_KEY": "${NOTION_TOKEN}" },
      "description": "Notion pages and databases"
    }
  },
  "toolPrefix": true,
  "connectionTimeoutMs": 5000,
  "requestTimeoutMs": 60000
}

Modes

Router mode — the agent calls mcp(server="todoist", action="list") to discover, then mcp(server="todoist", tool="find-tasks", params={...}) to execute.

Direct mode — tools are registered as todoist_find_tasks, github_list_repos, etc.

Transports

Environment variables

Secrets go in ~/.mcp-bridge/.env (chmod 600 on init):

TODOIST_API_TOKEN=your-token-here
GITHUB_TOKEN=ghp_xxxxx
NOTION_TOKEN=ntn_xxxxx

Use ${VAR_NAME} in config — resolved from .env + system env.

CLI Reference

mcp-bridge                        # Start in stdio mode (default)
mcp-bridge --sse --port 3000      # Start as SSE server
mcp-bridge --http --port 3000     # Start as HTTP server
mcp-bridge --verbose              # Info-level logs to stderr
mcp-bridge --debug                # Full protocol logs to stderr
mcp-bridge --config ./my.json     # Custom config file

mcp-bridge init                   # Create ~/.mcp-bridge/ with template
mcp-bridge install <server>       # Install from catalog
mcp-bridge catalog                # List available servers
mcp-bridge servers                # List configured servers
mcp-bridge search <query>         # Search catalog by keyword
mcp-bridge update [--check]       # Check for / install updates
mcp-bridge --version              # Print version

Server Catalog

Built-in catalog with pre-configured servers:

mcp-bridge install todoist    # Interactive setup with API key prompt
mcp-bridge catalog            # Full list
mcp-bridge search payments    # Search by keyword

Library Usage

Use as a dependency in your own MCP server or OpenClaw plugin:

import { McpRouter, StandaloneServer, loadConfig } from "@aiwerk/mcp-bridge";

// Quick start
const config = loadConfig({ configPath: "./config.json" });
const server = new StandaloneServer(config, console);
await server.startStdio();

// Use the router directly
import { McpRouter } from "@aiwerk/mcp-bridge";

const router = new McpRouter(servers, config, logger);
const result = await router.dispatch("todoist", "call", "find-tasks", { query: "today" });

Architecture

┌─────────────────┐     ┌──────────────────────────────────────┐
│  Claude Desktop  │     │  MCP Bridge                          │
│  Cursor          │◄───►│                                      │
│  Windsurf        │stdio│  ┌─────────┐  ┌──────────────────┐  │
│  OpenClaw        │     │  │ Router / │  │ Backend servers:  │  │
│  Any MCP client  │     │  │ Direct   │──│ • todoist (stdio) │  │
└─────────────────┘     │  │ mode     │  │ • github (stdio)  │  │
                        │  └─────────┘  │ • notion (stdio)  │  │
                        │               │ • stripe (sse)    │  │
                        │               └──────────────────┘  │
                        └──────────────────────────────────────┘

Related

• @aiwerk/openclaw-mcp-bridge — OpenClaw plugin wrapper (uses this package as core)
• MCP Specification — Model Context Protocol spec
• Awesome MCP Servers — Community server directory

License

MIT — AIWerk