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.

Starting an MCP server

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

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

Connecting RavenClaws as a client

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

Configuration

You can configure MCP servers in your config file:

ravenclaws.toml
[mcp]
servers = [
  { command = "npx", args = ["@modelcontextprotocol/server-filesystem", "/tmp"], name = "filesystem" },
  { command = "npx", args = ["@modelcontextprotocol/server-github"], name = "github" },
]

How it works

  1. RavenClaws spawns the MCP server process.
  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.

shell
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:

json-rpc
// 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" }
    ]
  }
}

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

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

VS Code MCP settings
{
  "mcp": {
    "servers": {
      "ravenclaws": {
        "command": "ravenclaws",
        "args": ["--mcp-server"]
      }
    }
  }
}

Multi-agent workflows

Chain multiple RavenClaws instances together:

shell
# 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.