Mcp

Name: Mcp
Rating: 3.5 (1 reviews)
Author: Startup-Suite

By Startup-Suite 👁 2 views ▲ 0 votes

OpenClaw MCP integration plugin — connect agents to any MCP server (HTTP, SSE, stdio)

GitHub

Install

npm install

#

Configuration Example

{
  "plugins": {
    "entries": {
      "mcp-integration": {
        "enabled": true,
        "config": {
          "enabled": true,
          "servers": {
            "example-server": {
              "enabled": true,
              "transport": "http",
              "url": "http://localhost:3000/mcp"
            }
          }
        }
      }
    }
  }
}

README

# OpenClaw MCP Integration Plugin

**Model Context Protocol (MCP) integration for OpenClaw** - Connect to MCP servers and use their tools seamlessly within OpenClaw.

## 🎯 Overview

This plugin enables OpenClaw to connect to any MCP (Model Context Protocol) server and expose its tools to AI agents. It implements the MCP Streamable HTTP transport specification and provides a unified interface for calling external MCP tools.

> ✅ **Real Working Example:** See [REAL_EXAMPLE_KR_LEGAL.md](docs/REAL_EXAMPLE_KR_LEGAL.md) for a complete, tested configuration with kr-legal-search (no API key required!).

### Key Features

✅ **HTTP/SSE Transport** - Full support for MCP Streamable HTTP with Server-Sent Events  
✅ **Dynamic Tool Discovery** - Automatically discovers and registers tools from MCP servers  
✅ **Multi-Server Support** - Connect to multiple MCP servers simultaneously  
✅ **Unified Interface** - All MCP tools accessible through a single `mcp` tool  
✅ **Error Handling** - Robust error handling and logging  

## 📋 Prerequisites

- **OpenClaw**: Version 2026.1.0 or higher
- **Node.js**: 18.0.0 or higher
- **MCP Server**: Any MCP-compliant server with HTTP transport

## 🚀 Installation

### Method 1: Via OpenClaw Extensions

```bash
# Clone into OpenClaw extensions directory
cd ~/.openclaw/extensions/
git clone https://github.com/yourorg/mcp-integration.git

# Install dependencies
cd mcp-integration
npm install

# Restart OpenClaw
openclaw gateway restart
```

### Method 2: Manual Installation

```bash
# Clone repository
git clone https://github.com/yourorg/mcp-integration.git
cd mcp-integration

# Install dependencies
npm install

# Link to OpenClaw
ln -s $(pwd) ~/.openclaw/extensions/mcp-integration

# Restart OpenClaw
openclaw gateway restart
```

## ⚙️ Configuration

### Basic Configuration

Add to `~/.openclaw/openclaw.json`:

```json
{
  "plugins": {
    "entries": {
      "mcp-integration": {
        "enabled": true,
        "config": {
          "enabled": true,
          "servers": {
            "example-server": {
              "enabled": true,
              "transport": "http",
              "url": "http://localhost:3000/mcp"
            }
          }
        }
      }
    }
  }
}
```

### Configuration Schema

```typescript
{
  enabled: boolean;              // Enable/disable plugin (default: true)
  servers: {
    [serverName: string]: {
      enabled: boolean;          // Enable/disable this server (default: true)
      transport: "http";         // Transport type (currently only http supported)
      url: string;               // Server URL (e.g., "http://localhost:3000/mcp")
    }
  }
}
```

### Multiple Servers Example

```json
{
  "plugins": {
    "entries": {
      "mcp-integration": {
        "enabled": true,
        "config": {
          "enabled": true,
          "servers": {
            "kr-legal": {
              "enabled": true,
              "transport": "http",
              "url": "http://localhost:3000/mcp"
            },
            "database": {
              "enabled": true,
              "transport": "http",
              "url": "http://localhost:3001/mcp"
            },
            "weather": {
              "enabled": true,
              "transport": "http",
              "url": "http://localhost:3002/mcp"
            }
          }
        }
      }
    }
  }
}
```

## 🛠️ Usage

### The `mcp` Tool

Once configured, the plugin registers a single `mcp` tool that provides access to all connected MCP servers.

#### List Available Tools

**In OpenClaw chat:**
```
User: List all MCP tools

AI: I'll check what MCP tools are available.

[Uses tool: mcp with action=list]

Available MCP tools:
- kr-legal:search_statute - Search Korean statutes
- kr-legal:search_case_law - Search court decisions
- database:query - Execute database query
- weather:get_forecast - Get weather forecast
```

**Tool call:**
```json
{
  "tool": "mcp",
  "args": {
    "action": "list"
  }
}
```

**Response:**
```json
[
  {
    "id": "kr-legal:search_statute",
    "server": "kr-legal",
    "name": "search_statute",
    "description": "Search Korean statutes and regulations",
    "inputSchema": {
      "type": "object",
      "properties": {
        "query": { "type": "string" },
        "limit": { "type": "number" }
      },
      "required": ["query"]
    }
  },
  {
    "id": "database:query",
    "server": "database",
    "name": "query",
    "description": "Execute SQL query",
    "inputSchema": {
      "type": "object",
      "properties": {
        "sql": { "type": "string" }
      },
      "required": ["sql"]
    }
  }
]
```

#### Call an MCP Tool

**In OpenClaw chat:**
```
User: Search for Korean labor law

AI: I'll search Korean legal statutes for labor law.

[Uses tool: mcp with action=call, server=kr-legal, tool=search_statute]

Found 15 statutes related to labor law...
```

**Tool call:**
```json
{
  "tool": "mcp",
  "args": {
    "action": "call",
    "server": "kr-legal",
    "tool": "search_statute",
    "args": {
      "query": "노동법",
      "limit": 5
    }
  }
}
```

**Response:**
```json
{
  "content": [
    {
      "type": "text",
      "text": "{\"results\":[{\"title\":\"근로기준법\",\"statute_id\":\"0065\",...}]}"
    }
  ]
}
```

## 🏗️ Architecture

### Component Diagram

```
┌─────────────────────────────────────────────┐
│           OpenClaw Core                     │
│  ┌───────────────────────────────────────┐  │
│  │  Agent (main/admin/chat)              │  │
│  └────────────────┬──────────────────────┘  │
│                   │                          │
│                   ▼                          │
│  ┌───────────────────────────────────────┐  │
│  │  Tool System                          │  │
│  │  - Calls mcp tool                     │  │
│  └────────────────┬──────────────────────┘  │
└───────────────────┼──────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────┐
│      MCP Integration Plugin                 │
│  ┌───────────────────────────────────────┐  │
│  │  MCPManager                           │  │
│  │  - Manages connections                │  │
│  │  - Routes tool calls                  │  │
│  │  - Lists available tools              │  │
│  └────────────┬──────────────────────────┘  │
│               │                             │
│  ┌────────────┴──────────────┐              │
│  │                           │              │
│  ▼                           ▼              │
│  Client 1                  Client 2         │
│  (kr-legal)                (database)       │
└──┼────────────────────────────┼─────────────┘
   │                            │
   ▼                            ▼
┌─────────────┐          ┌─────────────┐
│ MCP Server  │          │ MCP Server  │
│ (HTTP/SSE)  │          │ (HTTP/SSE)  │
└─────────────┘          └─────────────┘
```

### Class Structure

```typescript
class MCPManager {
  clients: Map<string, { client, transport }>;
  tools: Map<string, { server, tool, client }>;
  
  async connectServer(name: string, config: ServerConfig): Promise<Tool[]>;
  async callTool(serverName: string, toolName: string, args: any): Promise<any>;
  listTools(): ToolInfo[];
  async disconnect(): Promise<void>;
}

class StreamableHTTPClientTransport {
  constructor(url: string, options?: TransportOptions);
  
  async start(): Promise<void>;
  async send(message: JSONRPCRequest): Promise<JSONRPCResponse>;
  async close(): Promise<void>;
  
  onmessage?: (message: JSONRPCMessage) => void;
  onerror?: (error: Error) => void;
  onclose?: () => void;
}
```

## 🔄 Request Flow

### Tool Call Sequence

```mermaid
sequenceDiagram
    participant User
    participant Agent
    participant ToolSystem
    participant MCPPlugin
    participant MCPClient
    participant MCPServer

    User->>Agent: "Search for labor law"
    Agent->>ToolSystem: mcp(action=call, server=kr-legal, tool=search_statute)
    ToolSystem->>MCPPlugin: execute(params)
    MCPPlugin->>MCPClient: callTool(search_statute, {query: "노동법"})
    MCPClient->>MCPServer: POST /mcp {method: tools/call, params: {...}}
    MCPServer-->>MCPClient: {result: {...}}
    MCPClient-->>MCPPlugin: {content: [...]}
    MCPPlugin-->>ToolSystem: {content: [...]}
    ToolSystem-->>Agent: Tool result
    Agent-->>User: "Found 15 statutes..."
```

## 📊 HTTP Transport Implementation

### Streamable HTTP Specification

This plugin implements the MCP Streamable HTTP transport:

**POST Request** (Client to Server):
```http
POST /mcp HTTP/1.1
Content-Type: application/json
mcp-session-id: session-123

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_statute",
    "arguments": {"query": "민법"}
  }
}
```

**GET SSE Stream** (Server to Client, optional):
```http
GET /mcp HTTP/1.1
Accept: text/event-stream
mcp-session-id: session-123

# Server can send:
event: message
data: {"jsonrpc":"2.0","id":1,"result":{...}}
```

### Session Management

- Session ID is generated on first connection
- Persisted across requests via `mcp-session-id` header
- Allows server to maintain state

## 🔧 Development

### Project Structure

```
mcp-integration/
├── src/
│   ├── index.js             # Main plugin entry point
│   └── http-transport.js    # HTTP/SSE transport implementation
├── config/
│   └── openclaw.plugin.json # Plugin metadata and config schema
├── package.json             # npm dependencies
└── README.md                # This file
```

### Key Files

**index.js**
- Exports OpenClaw plugin registration function
- Implements MCPManager class
- Registers the `mcp` tool
- Handles server connections and tool routing

**http-transport.js**
- Implements `StreamableHTTPClientTransport` class
- Handles HTTP POST requests
- Manages SSE stream for server messages
- Implements MCP transport interface

**openclaw.plugin.json**
- Plugin metadata (id, name, version)
- Configuration schema
- OpenClaw version requirements

### Adding Debug Logging

Enable debug mode 

... (truncated)

integration