Docs / MCP integration

MCP integration

RavenClaws supports the Model Context Protocol (MCP) for connecting to external tools and services. This guide covers both MCP client and server modes.

Overview

MCP provides a standardized way for AI agents to discover and use external tools. RavenClaws can:

• Act as an MCP client — connect to MCP servers and use their tools.
• Act as an MCP server — expose RavenClaws' built-in tools to other MCP clients.

MCP client mode

In client mode, RavenClaws connects to one or more MCP servers and discovers their available tools. The agent can then use those tools during task execution.

Transport types

RavenClaws supports two MCP transport types:

Stdio transport

Starting an MCP server

First, you need an MCP server running. Here's an example using the official MCP filesystem server:

npx @modelcontextprotocol/server-filesystem /path/to/allowed/directory

Connecting RavenClaws as a client (Stdio)

# Connect to an MCP server via stdio
ravenclaws --mcp-client "npx @modelcontextprotocol/server-filesystem /tmp" --exec "List files in the current directory"

SSE transport

SSE (Server-Sent Events) transport allows RavenClaws to connect to MCP servers over HTTP, which is ideal for remote or containerized MCP servers.

Connecting RavenClaws as a client (SSE)

Configure SSE-based MCP servers in your config file:

[mcp]
servers = [
  { name = "playwright", url = "http://playwright-mcp:8080/sse" },
  { name = "postgres", url = "http://postgres-mcp:8081/sse" },
]

How SSE transport works

1. RavenClaws connects to the SSE endpoint via HTTP GET.
2. The server sends an endpoint event with the message endpoint URL.
3. RavenClaws sends JSON-RPC requests via HTTP POST to the message endpoint.
4. The server sends JSON-RPC responses via the SSE stream.
5. Automatic reconnection with exponential backoff on disconnection.

Configuration (all transports)

You can configure MCP servers in your config file:

[mcp]
servers = [
  # Stdio transport
  { command = "npx", args = ["@modelcontextprotocol/server-filesystem", "/tmp"], name = "filesystem" },
  { command = "npx", args = ["@modelcontextprotocol/server-github"], name = "github" },
  # SSE transport
  { name = "playwright", url = "http://playwright-mcp:8080/sse" },
]

How it works

1. RavenClaws connects to MCP servers (via stdio or SSE).
2. Discovers available tools via the tools/list endpoint.
3. Registers discovered tools in the ToolRegistry.
4. When the agent calls a tool, RavenClaws sends a tools/call request.
5. Results are returned to the agent for further processing.

MCP server mode

In server mode, RavenClaws exposes its built-in tools (shell, read/write file, web fetch, web search) as MCP tools that other AI agents can discover and use.

Stdio server

ravenclaws --mcp-server

This starts RavenClaws in MCP server mode, listening on stdio for JSON-RPC 2.0 requests. Any MCP-compatible client can connect:

// Request: List available tools
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

// Response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      { "name": "shell", "description": "Execute a shell command" },
      { "name": "read_file", "description": "Read a file from the filesystem" }
    ]
  }
}

SSE server

RavenClaws also supports MCP over SSE (Server-Sent Events) transport, which allows remote MCP clients to connect over HTTP.

# Default port 8081
ravenclaws --mcp-sse-server

# Custom host and port
ravenclaws --mcp-sse-server --mcp-sse-host 127.0.0.1 --mcp-sse-port 9090

The SSE server provides two endpoints:

Connecting from OpenClaw

{
  "mcpServers": {
    "ravenclaws": {
      "url": "http://ravenclaws:8081/sse"
    }
  }
}

Connecting from Claude Desktop

{
  "mcpServers": {
    "ravenclaws": {
      "url": "http://localhost:8081/sse"
    }
  }
}

How SSE server works

1. Client connects to GET /sse and receives an endpoint event with the message URL.
2. Client sends JSON-RPC requests via POST /message.
3. Server processes requests through PolicyEngine, Sandbox, and AuditLog.
4. Server sends JSON-RPC responses via the SSE stream.
5. Multiple concurrent clients are supported via separate SSE connections.

Security

When running in MCP server mode, all tool calls are still subject to:

• PolicyEngine — deny-by-default allow-lists for shell, path, and network access.
• Sandbox — workdir jail with resource limits.
• AuditLog — tamper-evident logging of all operations.

Use cases

IDE integration (Stdio)

Connect RavenClaws to VS Code via MCP for AI-assisted development:

{
  "mcp": {
    "servers": {
      "ravenclaws": {
        "command": "ravenclaws",
        "args": ["--mcp-server"]
      }
    }
  }
}

IDE integration (SSE)

Or connect via SSE transport for remote access:

{
  "mcp": {
    "servers": {
      "ravenclaws": {
        "url": "http://localhost:8081/sse"
      }
    }
  }
}

Multi-agent workflows

Chain multiple RavenClaws instances together:

# Agent 1: MCP SSE server with filesystem access
ravenclaws --mcp-sse-server --mcp-sse-port 8081 --config agent1.toml &

# Agent 2: MCP client using Agent 1's tools via SSE
ravenclaws --exec "Analyze the codebase and suggest improvements"

Or use stdio transport for local-only workflows:

# Agent 1: MCP server with filesystem access
ravenclaws --mcp-server --config agent1.toml &

# Agent 2: MCP client using Agent 1's tools
ravenclaws --mcp-client "ravenclaws --mcp-server --config agent2.toml" \
  --exec "Analyze the codebase and suggest improvements"

Best practices

1. Use allow-lists — configure allowed_paths and allowed_shell_commands in server mode.
2. Audit everything — always enable audit logging in production.
3. Sandbox untrusted code — enable the sandbox for MCP server mode.
4. Limit exposure — only expose the tools you need.
5. Monitor — use health endpoints to verify MCP connections.