# googleapis/genai-toolbox architecture

> Architecture diagram of the GitHub repository googleapis/genai-toolbox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/googleapis/genai-toolbox
- Repository: https://github.com/googleapis/genai-toolbox

## Overview

##### Project Type and Purpose
- This is an open-source MCP (Multi-Channel Protocol) server for databases (MCP Toolbox).
- It provides a centralized control plane to define, manage, and invoke “tools” (SQL operations, commands) against multiple database sources, handling connection pooling, authentication, telemetry, and dynamic reloading.
- Consumers include: CLI (`cmd/`), container image, and SDK clients (Python, JS, etc.), which load toolsets via HTTP/JSON-RPC and invoke database operations.

##### File Structure Analysis
- Top-level:
- `.ci/`, `.github/`: CI/CD and repo automation
- `cmd/`: CLI entrypoints (options.go, root.go)
- `internal/`: core packages
– `server/`: config loader, MCP API handlers, JSON-RPC implementations, lifecycle
– `sources/`: adapters for each DB type (Postgres, MySQL, BigQuery, Redis, etc.)
– `tools/`: implementations of tool kinds (execute SQL, list tables, etc.)
– `auth/`, `log/`, `telemetry/`: cross-cutting concerns
– `prebuiltconfigs/`: YAML templates for common sources/tools
– `util/`, `testutils/`: helpers
- `main.go`: bootstrap
- `docs/`, `.hugo/`: documentation site
- Configuration via a `tools.yaml` (not in repo) read by server to define sources, tools, toolsets.
- Testing: unit tests under each package, integration tests under `tests/`.

##### README Insights
Client ⟷ MCP Toolbox server ⟷ Databases
- Key features: dynamic reloading, built-in auth, OpenTelemetry tracing/metrics, plugin-style adapters.

a. Main Components
1. **Clients**
- CLI (cmd/root)
- Container image
- SDKs (Python, JS, Genkit, LangChain)
2. **MCP Toolbox Server**
- **Config Loader** (parses tools.yaml, prebuiltconfigs)
- **Tool Registry** (in-memory store of tool definitions & toolsets)
- **MCP API Layer**
- HTTP server / JSON-RPC handler (`internal/server/api.go`, `jsonrpc/`)
- **Auth Module** (`internal/auth`)
- **Telemetry & Logging** (`internal/telemetry`, `internal/log`)
- **Source Adapter Manager** (loads appropriate adapter from `internal/sources/*`)
- **Execution Engine / Connection Pool** (`internal/sources/*`, `database/sql` under the hood)
3. **External Data Sources**
- Relational DBs: PostgreSQL, MySQL, MSSQL, SQLite
- Cloud DBs: BigQuery, Spanner, Bigtable
- NoSQL: Redis, Couchbase, Neo4j, Dgraph
- HTTP source, Valkey, etc.
b. Relationships & Data Flow
1. Client sends “load toolset” or “invoke tool” request over HTTP/JSON-RPC to MCP server.
2. MCP API Layer authenticates via Auth Module, logs request.
3. API Layer looks up the Tool definition in Tool Registry.
4. Execution Engine fetches a connection from Connection Pool for the configured Source.
5. Executes statement via Source Adapter, collects results.
6. Telemetry Module emits metrics/traces; Logging Module records events.
7. API Layer returns response to Client.
c. Architectural Patterns & Principles
- **Plugin / Adapter Pattern** for database sources and tool implementations
- **Control-Plane / Data-Plane Separation**:
- Control plane: config loader, registry, dynamic reloading
- Data plane: query execution, connection pooling
- **MCP (JSON-RPC) Protocol** layer abstraction
- **Dependency Injection** via interfaces (for sources, tools, telemetry)
d. Key Technologies & Frameworks
- Go modules (go.mod)
- Standard library: `net/http`, `database/sql`
- OpenTelemetry SDK
- JSON-RPC implementation under `internal/server/mcp/jsonrpc`
- Hugo for docs site
- GitHub Actions & Cloud Build for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Clients" 
        direction TB
        CLI["CLI (cmd/root.go, cmd/options.go)"]:::client
        SDK["SDKs (Python, JS, Genkit, LangChain)"]:::client
        Container["Container Image (Dockerfile)"]:::client
    end

    %% MCP Toolbox Server
    subgraph "MCP Toolbox Server"
        direction TB

        subgraph "Control Plane" 
            direction TB
            ConfigLoader["Config Loader"]:::control
            PrebuiltConfigs["Prebuilt Configs"]:::control
            ToolRegistry["Tool Registry"]:::control
            ToolSets["Toolsets"]:::control
            MCPAPI["MCP API Layer"]:::control
            AuthMod["Auth Module"]:::control
            Lifecycle["Lifecycle Utilities"]:::control
            ControlPlaneEntrypoint["Control-Plane Entrypoint"]:::control
        end

        subgraph "Data Plane"
            direction TB
            AdapterMgr["Source Adapter Manager"]:::data
            ExecEngine["Execution Engine / Connection Pool"]:::data
        end

        subgraph "Cross-Cutting"
            direction TB
            Telemetry["Telemetry Module"]:::cross
            Logging["Logging Module"]:::cross
        end
    end

    %% External Data Sources
    subgraph "External Data Sources"
        direction TB
        Postgres[(PostgreSQL)]:::db
        MySQL[(MySQL)]:::db
        BigQuery[(BigQuery)]:::db
        Redis[(Redis)]:::db
        OtherDBs[(Other DBs & HTTP Sources)]:::db
    end

    %% Connections
    CLI -->|HTTP/JSON-RPC| MCPAPI
    SDK -->|HTTP/JSON-RPC| MCPAPI
    Container -->|HTTP/JSON-RPC| MCPAPI

    MCPAPI -->|authenticate| AuthMod
    MCPAPI -->|lookup tool| ToolRegistry
    ToolRegistry -->|fetch toolset| ToolSets
    MCPAPI -->|invoke| ExecEngine
    ExecEngine -->|get adapter| AdapterMgr
    ExecEngine -->|execute| Postgres
    ExecEngine -->|execute| MySQL
    ExecEngine -->|execute| BigQuery
    ExecEngine -->|execute| Redis
    ExecEngine -->|execute| OtherDBs
    ConfigLoader -->|loads| ToolRegistry
    PrebuiltConfigs -->|provides| ConfigLoader
    Lifecycle -->|manages| ControlPlaneEntrypoint

    %% Telemetry & Logging taps
    AuthMod -->|emit events| Telemetry
    MCPAPI -->|emit events| Telemetry
    ExecEngine -->|emit metrics| Telemetry
    AuthMod -->|log| Logging
    MCPAPI -->|log| Logging
    ExecEngine -->|log| Logging

    %% Click Events
    click CLI "https://github.com/googleapis/genai-toolbox/blob/main/cmd/root.go"
    click Container "https://github.com/googleapis/genai-toolbox/tree/main/Dockerfile"
    click SDK "https://github.com/googleapis/genai-toolbox/blob/main/docs/en/sdks/_index.md"
    click ConfigLoader "https://github.com/googleapis/genai-toolbox/blob/main/internal/server/config.go"
    click PrebuiltConfigs "https://github.com/googleapis/genai-toolbox/blob/main/internal/prebuiltconfigs/prebuiltconfigs.go"
    click ToolRegistry "https://github.com/googleapis/genai-toolbox/blob/main/internal/tools/tools.go"
    click ToolSets "https://github.com/googleapis/genai-toolbox/blob/main/internal/tools/toolsets.go"
    click MCPAPI "https://github.com/googleapis/genai-toolbox/blob/main/internal/server/api.go"
    click AuthMod "https://github.com/googleapis/genai-toolbox/blob/main/internal/auth/auth.go"
    click Telemetry "https://github.com/googleapis/genai-toolbox/blob/main/internal/telemetry/telemetry.go"
    click Logging "https://github.com/googleapis/genai-toolbox/blob/main/internal/log/logger.go"
    click AdapterMgr "https://github.com/googleapis/genai-toolbox/blob/main/internal/sources/sources.go"
    click Lifecycle "https://github.com/googleapis/genai-toolbox/blob/main/internal/server/mcp/util/lifecycle.go"
    click ControlPlaneEntrypoint "https://github.com/googleapis/genai-toolbox/blob/main/internal/server/mcp/mcp.go"

    %% Styles
    classDef client fill:#EFEFFF,stroke:#3366FF,stroke-width:1px
    classDef control fill:#E0F7FA,stroke:#00796B,stroke-width:1px
    classDef data fill:#E8F5E9,stroke:#2E7D32,stroke-width:1px
    classDef cross fill:#FFF3E0,stroke:#F57C00,stroke-width:1px
    classDef db fill:#F3E5F5,stroke:#6A1B9A,stroke-width:1px
```
