Skip to content

MCP Architecture

Overview

ravenbot uses the Model Context Protocol (MCP) via the official Go SDK to connect to external tools. This allows the bot to integrate with the official ecosystem of MCP-compliant servers.

Architecture

ravenbot acts as an MCP Host using the google.golang.org/adk/tool/mcptoolset package. Each MCP server defined in config.json is initialized at startup and assigned to specific sub-agents.

graph TD
    Bot[RavenBot Core] --> ResearchAssistant
    Bot --> SystemManager
    Bot --> Jules
    ResearchAssistant --> mcptoolset1[mcptoolset]
    SystemManager --> mcptoolset2[mcptoolset]
    Jules --> mcptoolset3[mcptoolset]
    mcptoolset1 --> BS[Brave Search]
    mcptoolset1 --> WX[Weather]
    mcptoolset1 --> MEM[Memory]
    mcptoolset1 --> FS[Filesystem]
    mcptoolset1 --> ST[Sequential Thinking]
    mcptoolset2 --> SM[SysMetrics]
    mcptoolset3 --> GH[GitHub]

MCP Server Inventory

Server Command Assigned To Purpose
brave-search npx -y @modelcontextprotocol/server-brave-search ResearchAssistant Web search
weather goweathermcp ResearchAssistant Weather by city/coords
memory npx -y @modelcontextprotocol/server-memory ResearchAssistant Knowledge graph (long-term memory)
filesystem npx -y @modelcontextprotocol/server-filesystem ResearchAssistant Read/search server files
sequential-thinking npx -y @modelcontextprotocol/server-sequential-thinking ResearchAssistant Step-by-step complex reasoning
sysmetrics sysmetrics-mcp SystemManager CPU, memory, disk, temps, Docker
github npx -y @modelcontextprotocol/server-github Jules Full GitHub API access

Key Components

1. Configuration (config.json)

MCP servers are defined under "mcpServers". Each entry specifies a command and arguments:

"mcpServers": {
  "brave-search": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-brave-search"],
    "env": { "BRAVE_API_KEY": "$BRAVE_API_KEY" }
  }
}

Environment variables in env values (e.g., $BRAVE_API_KEY) are expanded at runtime from the host environment.

2. Official Toolsets (google.golang.org/adk/tool/mcptoolset)

ravenbot uses the ADK's native mcptoolset which provides: - Standard Transports: mcp.CommandTransport for local processes, mcp.SSEClientTransport for remote streams. - Auto-Discovery: Queries servers for available tools and capabilities on startup. - Schema Mapping: Converts MCP tool schemas into Gemini-compatible function declarations.

3. Agent Integration

Toolsets are injected into sub-agents via the Tools field in llmagent.Config. Each sub-agent only sees tools from its assigned MCP servers:

researchAssistant, _ := llmagent.New(llmagent.Config{
    Name:  "ResearchAssistant",
    Tools: []tool.ToolSet{braveSearch, weather, memory, filesystem, sequentialThinking},
})

The root agent (ravenbot-flash, ravenbot-pro) delegates to sub-agents via transfer_to_agent and does not directly execute MCP tools.

Adding a New MCP Server

  1. Add the server config to config.json under "mcpServers".
  2. Assign the toolset to the appropriate sub-agent in internal/agent/agent.go.
  3. Update the sub-agent's system prompt in config.json to describe the new tools.
  4. Restart the bot — the new tools are discovered automatically.

Benefits

  1. Production Grade: Built on the official modelcontextprotocol/go-sdk.
  2. Robust Transports: Handles process lifecycles and stream reconnections natively.
  3. Unified Tooling: MCP tools appear to the agent exactly like native Go functions.
  4. Extensible: Any MCP-compliant server can be added with a JSON config entry.