@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)
• Intent routing: say what you need in plain language, the bridge finds the right tool
• Schema compression: tool descriptions compressed ~57%, full schema on demand
• Security layer: trust levels, tool deny/allow lists, result size limits
• Direct mode: all tools registered individually with automatic prefixing
• 3 transports: stdio, SSE, streamable-http
• Built-in catalog: 14 pre-configured servers, install 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": []
    }
  }
}

Recipe Spec v2

Bundled servers now ship with recipe.json using Universal Recipe Spec v2.0. During install, MCP Bridge prefers recipe.json when present and falls back to legacy config.json (v1) for backwards compatibility.

• Spec: docs/universal-recipe-spec.md
• Runtime compatibility: v1 and v2 are both supported
• Existing v1-only servers continue to work unchanged

For third-party recipe authors:

1. Author recipe.json per the spec above.
2. Validate your recipe before publishing:

npx @aiwerk/mcp-bridge validate-recipe ./recipe.json

config.json (v1) remains supported, but recipe.json (v2) is the recommended format going forward.

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,
  "schemaCompression": {
    "enabled": true,
    "maxDescriptionLength": 80
  }
}

Schema Compression

In router mode, tool descriptions from upstream servers can be verbose (100-300+ chars each). Schema compression truncates them to save tokens:

• Enabled by default — descriptions capped at 80 characters
• Cuts at sentence boundary when possible, otherwise word boundary
• Use action=schema to retrieve the full uncompressed schema for any tool on demand

"schemaCompression": {
  "enabled": true,
  "maxDescriptionLength": 80
}

Token savings example: 30 Todoist tools: 2800 tokens uncompressed -> ~1200 compressed (57% reduction).

To get full details for a specific tool:

mcp(server="todoist", action="schema", tool="find-tasks")

Set "enabled": false to disable compression and return full descriptions.

Intent Routing

Instead of specifying the exact server and tool, describe what you need:

mcp(action="intent", intent="find my tasks for today")

The bridge uses vector embeddings to match your intent to the right server and tool automatically. Returns the best match with a confidence score and alternatives.

Embedding providers (configured via intentRouting.embedding):

"intentRouting": {
  "embedding": "auto",
  "minScore": 0.3
}

• auto (default): tries gemini, openai, ollama, then keyword - in order of availability
• minScore: minimum confidence to return a match (0-1, default: 0.3)
• Index is built lazily on first action=intent call

Security

Three layers of protection for tool results:

Trust Levels

Per-server control over how results are passed to the agent:

"servers": {
  "my-trusted-server": {
    "trust": "trusted"
  },
  "unknown-server": {
    "trust": "untrusted"
  },
  "sketchy-server": {
    "trust": "sanitize"
  }
}

Tool Filter

Control which tools are visible and callable per server:

"servers": {
  "github": {
    "toolFilter": {
      "deny": ["delete_repository"],
      "allow": ["list_repos", "create_issue", "search_code"]
    }
  }
}

• deny: block specific dangerous tools
• allow: whitelist mode - only these tools are visible
• If both: allowed tools minus denied ones
• Applied in both tool listing and execution (defense in depth)

Max Result Size

Prevent oversized responses from consuming your context:

{
  "maxResultChars": 50000,
  "servers": {
    "verbose-server": {
      "maxResultChars": 10000
    }
  }
}

• Global default + per-server override
• Truncated results include _truncated: true and _originalLength

Adaptive Promotion

Frequently used tools can be automatically "promoted" to standalone tools alongside the mcp meta-tool. The promotion system tracks usage and reports which tools qualify — the host environment (e.g., OpenClaw plugin) decides how to register them.

"adaptivePromotion": {
  "enabled": true,
  "maxPromoted": 10,
  "minCalls": 3,
  "windowMs": 86400000,
  "decayMs": 172800000
}

Use action="promotions" to check current promotion state:

mcp(action="promotions")

Returns promoted tools (sorted by frequency) and full usage stats. All tracking is in-memory — promotion rebuilds naturally from usage after restart.

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        │ SSE │  │  Router   │  │Security│  │  Backend   │  │
│  Any MCP client  │ HTTP│  │  Intent   │─►│ Trust  │─►│  servers:  │  │
└─────────────────┘     │  │  Schema   │  │ Filter │  │  • todoist │  │
                        │  │  Compress │  │ Limit  │  │  • github  │  │
                        │  └──────────┘  └────────┘  │  • notion  │  │
                        │                            │  • stripe  │  │
                        │                            └────────────┘  │
                        └──────────────────────────────────────────────┘

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