openclaw-mcp-bridge

An MCP (Model Context Protocol) client plugin for OpenClaw that connects agents to remote MCP servers over Streamable HTTP with full OAuth 2.1 authentication.

Features

• Streamable HTTP transport — MCP 2025-03-26 spec compliant (POST/GET/DELETE + SSE)
• stdio transport — subprocess-based servers with newline-delimited JSON-RPC
• Legacy SSE transport — backwards-compatible HTTP+SSE (2024-11-05 spec)
• OAuth 2.1 authentication — PKCE (S256), dynamic client registration, RFC 9728 protected resource metadata, RFC 8414 auth server discovery
• API key auth — simple Bearer token alternative for servers that don't need OAuth
• Multi-server management — connect to many MCP servers simultaneously with automatic tool namespacing (server__tool)
• Session management — Mcp-Session-Id tracking, automatic re-initialization on session expiry
• SSE resumability — Last-Event-ID reconnection for broken streams
• Dynamic tool discovery — periodic re-discovery of server tools with configurable intervals
• Hot config reload — add/remove/update servers without restarting

Requirements

• Node.js >= 22
• OpenClaw >= 2025.1.0

Installation

# Install directly from GitHub
pnpm add github:fsaint/openclaw-mcp-bridge

# Or from source
git clone https://github.com/fsaint/openclaw-mcp-bridge.git
cd openclaw-mcp-bridge
pnpm install
pnpm build
openclaw plugins install --link .
openclaw gateway restart

Configuration

Add to your openclaw.json:

{
  "plugins": {
    "entries": {
      "plugin-mcp-client": {
        "enabled": true,
        "config": {
          "servers": {
            "tavily": {
              "url": "https://mcp.tavily.com/mcp",
              "apiKey": "tvly-..."
            },
            "github": {
              "url": "https://mcp.github.com/sse",
              "auth": {
                "clientId": "your-client-id"
              }
            },
            "local-tools": {
              "url": "stdio://local",
              "transport": "stdio",
              "command": "npx",
              "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
            }
          },
          "debug": false
        }
      }
    }
  }
}

Server options

| Option | Type | Default | Description | |--------|------|---------|-------------| | url | string | — | MCP server endpoint URL | | transport | "http" \| "stdio" | "http" | Transport type | | command | string | — | Command for stdio transport | | args | string[] | — | Arguments for stdio command | | env | Record<string, string> | — | Environment variables for stdio subprocess | | apiKey | string | — | Static Bearer token | | auth | object | — | OAuth 2.1 config (see below) | | auth.clientId | string | — | Pre-registered OAuth client ID | | auth.clientSecret | string | — | OAuth client secret (confidential clients) | | auth.authorizationServerUrl | string | — | Override auth server URL | | auth.scopes | string[] | — | Custom scopes to request | | toolPrefix | string | server name | Namespace prefix for tools | | connectTimeoutMs | number | 10000 | Connection timeout (ms) | | requestTimeoutMs | number | 30000 | Per-request timeout (ms) | | enabled | boolean | true | Enable/disable this server |

Global options

| Option | Type | Default | Description | |--------|------|---------|-------------| | toolDiscoveryInterval | number | 300000 | Re-discover tools every N ms | | maxConcurrentServers | number | 20 | Max simultaneous connections | | debug | boolean | false | Enable debug logging |

Usage

Once configured, MCP tools appear as regular agent tools with namespaced names:

tavily__search
github__create_issue
local-tools__read_file

Slash commands

| Command | Description | |---------|-------------| | /mcp servers | List all configured servers and their status | | /mcp tools | List all discovered tools | | /mcp connect <server> | Connect to a specific server | | /mcp disconnect <server> | Disconnect from a server | | /mcp auth <server> | Trigger OAuth authentication flow |

Architecture

┌──────────────────────────────────────────────┐
│               OpenClaw Gateway               │
│                                              │
│  Skill (SKILL.md) ──▶ Plugin (Tool Ext)     │
│                          │                   │
│          ┌───────────────┼──────────┐        │
│          ▼               ▼          ▼        │
│    MCPManager      AuthManager   ToolRegistry│
│          │               │                   │
└──────────┼───────────────┼───────────────────┘
           │               │
           ▼               ▼
    ┌─────────────┐ ┌─────────────┐
    │ MCP Servers  │ │ Auth Server │
    └─────────────┘ └─────────────┘

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Run tests
pnpm test

# Watch mode
pnpm test:watch

# Coverage
pnpm test:coverage

# Type check
pnpm lint

Project structure

src/
  index.ts                    Plugin entry point
  config-schema.ts            TypeBox configuration schema
  types.ts                    JSON-RPC 2.0 + MCP type definitions
  jsonrpc.ts                  JSON-RPC encode/decode/validate
  manager/
    mcp-manager.ts            Multi-server connection lifecycle
    tool-registry.ts          Dynamic tool registration + namespacing
  transport/
    streamable-http.ts        Streamable HTTP transport (POST/GET/DELETE + SSE)
    sse-parser.ts             Server-Sent Events stream parser
    stdio.ts                  stdio transport (subprocess)
    legacy-sse.ts             Backwards-compat HTTP+SSE
  auth/
    auth-manager.ts           OAuth 2.1 orchestrator
    discovery.ts              Protected Resource + Auth Server metadata
    pkce.ts                   PKCE S256 code challenge generation
    client-registration.ts    Dynamic Client Registration
    token-store.ts            Encrypted token persistence
    callback-server.ts        Local HTTP server for OAuth redirects
  commands/
    mcp-manage.ts             /mcp subcommand handler
skills/
  mcp/
    SKILL.md                  Agent-facing skill definition

License

MIT