# google/mcp-security architecture

> Architecture diagram of the GitHub repository google/mcp-security, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/google/mcp-security
- Repository: https://github.com/google/mcp-security

## Overview

##### Project Type and Purpose
- This is a collection of backend microservices (Python packages) implementing Google’s Model Context Protocol (MCP) servers for security operations and threat intelligence.
- The goal is to let MCP-aware clients (e.g., Claude Desktop, the cline.bot VS Code extension, or a Google ADK agent) interact with Google SecOps products (Chronicle, SOAR, GTI, SCC) or third-party integrations in a uniform way.

##### High-Level Architectural Components
a. Clients
- Google ADK Agent (web UI at localhost:8000)
- MCP clients (Claude Desktop, cline.bot) via stdio transport or HTTP (uv)
b. MCP Server Microservices
- SecOps MCP (`server/secops/secops_mcp/server.py`)
- SecOps SOAR MCP (`server/secops-soar/secops_soar_mcp/server.py`)
- GTI MCP (`server/gti/gti_mcp/server.py`)
- SCC MCP (`server/scc/scc_mcp.py`)
c. Integration Adapters (within each microservice)
- SecOps SOAR: dozens of “marketplace” modules (one per third-party or Google service)
- SecOps: tool modules for entity lookup, IOC matching, alerts, events, threat intel
- GTI & SCC: lightweight adapters to Google APIs (VirusTotal, Chronicle, Security Command Center)
d. External Services
- Google Cloud APIs (Chronicle, Security Command Center, Vertex AI / GenAI SDK)
- Third-party SaaS / security products (ServiceNow, Slack, AWS GuardDuty, etc.)
e. Documentation & CI/CD
- `docs/` folder with Sphinx-powered site, GitHub Actions for docs deployment
- `.github/workflows/deploy-docs.yml`

##### Relationships and Data Flows
- Clients → MCP Server: invoke MCP commands over STDIO or HTTP (Uvicorn/ASGI)
- MCP Server Core → Integration Adapters: load tool modules dynamically based on environment flags or CLI args
- Adapters → External Services: authenticate via ADC or API keys, call Google or third-party APIs, return responses
- Responses propagate back up: Adapter → Server Core → Client

##### Key Architectural Patterns
- Microservices: each MCP server is its own Python package, independently deployable
- Plugin/Adapter Pattern: SecOps SOAR server dynamically discovers and loads one Python module per integration
- Hexagonal (Ports & Adapters): core server logic defines MCP “ports,” adapters implement them for each external system
- Environment-driven Configuration: each server uses ENV Vars or `.env` files to enable/disable services

##### Technologies & Frameworks
- Python 3.11+, Uvicorn (ASGI server), FastAPI (likely underlying), Google ADK SDK, pytest for tests
- Sphinx for documentation, GitHub Actions for CI

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    subgraph "MCP Clients"
        direction TB
        ADKAgent["Google ADK Agent (Web UI)"]:::clients
        Claude["Claude Desktop / cline.bot"]:::clients
        Launcher["ADK Agent Launcher"]:::clients
    end

    %% Servers
    subgraph "SecOps MCP Server" 
        direction TB
        SecOpsCore["SecOps MCP Server Core"]:::servers
        subgraph "Integration Adapters"
            direction TB
            SecOpsAdapters["entity_lookup, ioc_matches, alerts…"]:::adapters
        end
    end

    subgraph "SecOps SOAR MCP Server"
        direction TB
        SOARCore["SecOps SOAR MCP Server Core"]:::servers
        SOARHttp["HTTP Client & Bindings"]:::adapters
        SOARUtils["Core Models & Utils"]:::adapters
        subgraph "Marketplace Modules"
            direction TB
            SOARMarket["100+ marketplace integrations"]:::adapters
        end
    end

    subgraph "GTI MCP Server"
        direction TB
        GTICore["GTI MCP Server Core"]:::servers
        GTIUtils["Utilities"]:::adapters
        GTIAdapters["Integration Adapters"]:::adapters
    end

    subgraph "SCC MCP Server"
        direction TB
        SCCCore["SCC MCP Server Core"]:::servers
    end

    %% External Services
    subgraph "External Services"
        direction TB
        GoogleAPIs["Google Cloud APIs (Chronicle, SCC, GenAI)"]:::external
        ThirdParty["Third-Party SaaS (ServiceNow, Slack, AWS GuardDuty)"]:::external
    end

    %% Documentation & CI/CD
    subgraph "Docs & CI/CD"
        direction TB
        DocsServers["Servers Overview"]:::docs
        DocsSOAR["SOAR Integrations Reference"]:::docs
        CIWorkflow["GitHub Actions deploy-docs.yml"]:::docs
    end

    %% Connections: Clients → Servers
    ADKAgent -->|HTTP/ASGI| SecOpsCore
    ADKAgent -->|HTTP/ASGI| SOARCore
    ADKAgent -->|HTTP/ASGI| GTICore
    ADKAgent -->|HTTP/ASGI| SCCCore
    Claude -->|STDIO| SecOpsCore
    Claude -->|STDIO| SOARCore
    Claude -->|STDIO| GTICore
    Claude -->|STDIO| SCCCore
    Launcher -->|starts| ADKAgent

    %% Servers → Adapters
    SecOpsCore -->|loads| SecOpsAdapters
    SOARCore -->|uses| SOARHttp
    SOARCore -->|uses| SOARUtils
    SOARCore -->|discovers| SOARMarket
    GTICore -->|loads| GTIUtils
    GTICore -->|loads| GTIAdapters

    %% Adapters → External Services
    SecOpsAdapters -->|ADC/API Key| GoogleAPIs
    SOARMarket -->|API Key| ThirdParty
    GTIAdapters -->|ADC/API Key| GoogleAPIs
    SCCCore -->|ADC/API Key| GoogleAPIs

    %% Documentation links
    ADKAgent -->|reference| DocsServers
    SOARMarket -->|reference| DocsSOAR
    DocsServers --> CIWorkflow

    %% Click Events
    click ADKAgent "https://github.com/google/mcp-security/blob/main/run-with-google-adk/google-mcp-security-agent/agent.py"
    click Launcher "https://github.com/google/mcp-security/blob/main/run-with-google-adk/run-adk-agent.sh"
    click SecOpsCore "https://github.com/google/mcp-security/blob/main/server/secops/secops_mcp/server.py"
    click SecOpsAdapters "https://github.com/google/mcp-security/tree/main/server/secops/secops_mcp/tools/"
    click SOARCore "https://github.com/google/mcp-security/blob/main/server/secops-soar/secops_soar_mcp/server.py"
    click SOARHttp "https://github.com/google/mcp-security/blob/main/server/secops-soar/secops_soar_mcp/http_client.py"
    click SOARUtils "https://github.com/google/mcp-security/tree/main/server/secops-soar/secops_soar_mcp/utils/"
    click SOARMarket "https://github.com/google/mcp-security/tree/main/server/secops-soar/secops_soar_mcp/marketplace/"
    click GTICore "https://github.com/google/mcp-security/blob/main/server/gti/gti_mcp/server.py"
    click GTIAdapters "https://github.com/google/mcp-security/tree/main/server/gti/gti_mcp/tools/"
    click GTIUtils "https://github.com/google/mcp-security/blob/main/server/gti/gti_mcp/utils.py"
    click SCCCore "https://github.com/google/mcp-security/blob/main/server/scc/scc_mcp.py"
    click DocsServers "https://github.com/google/mcp-security/tree/main/docs/servers/"
    click DocsSOAR "https://github.com/google/mcp-security/tree/main/docs/soar_integrations/"
    click CIWorkflow "https://github.com/google/mcp-security/blob/main/.github/workflows/deploy-docs.yml"

    %% Styles
    classDef clients fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef servers fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef adapters fill:#e6ccff,stroke:#333,stroke-width:1px
    classDef external fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef docs fill:#f2f2f2,stroke:#333,stroke-width:1px
```
