# crowdstrike/falcon-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/crowdstrike/falcon-mcp
- Repository: https://github.com/crowdstrike/falcon-mcp
- Video tour (about a minute): https://gitdiagram.com/crowdstrike/falcon-mcp/video

## Overview

##### Project type and purpose
- This is a Python-based MCP (Model Context Protocol) server and library (“falcon-mcp”) that
– Exposes AI-agent-friendly tools for interacting with the CrowdStrike Falcon platform
– Can run as a CLI tool, Dockerized microservice, or embedded library
– Provides modular security functions (detections, incidents, intel, hosts, spotlight, cloud, sensor usage, identity protection)

##### File structure
- Top-level entry points and configuration
– “falcon-mcp” CLI (via uvx or pip), Dockerfile, .env examples, pyproject.toml
- Core package “falcon_mcp”
– server.py: MCP server implementation
– client.py: OAuth2 HTTP client for CrowdStrike API
– registry.py: Maps MCP method names to module handlers
– common/: shared utilities (logging, errors, API scope definitions, helpers)
– modules/: plugin modules implementing business logic (base.py, cloud.py, detections.py, …)
– resources/: context docs and FQL guides for each module
- Tests and examples
– tests/: unit and end-to-end tests
– examples/: sample usage scripts
- CI/CD, docs, scripts
– .github/workflows, docs/, scripts/

##### README for architecture insights
- Server loads a configurable subset of modules at startup
- Supports three transports: stdio (JSON/RPC), SSE, streamable-HTTP
- Each module defines tools (actions) and resources (documentation endpoints)
- Server ↔ CrowdStrike API communication uses OAuth2 and REST

a. Main components
1. Entry Point
– CLI command (`falcon-mcp`), uvx, Docker container, or library instantiation
2. Transport Adapters
– stdio adapter (JSON I/O)
– SSE adapter (HTTP event stream)
– Streamable-HTTP adapter (chunked responses)
3. FalconMCPServer Core
– Argument/env parsing
– Module registry loading
– Request dispatcher
4. Modules & Resources
– Module plugins (detections, incidents, intel, hosts, spotlight, cloud, sensor usage, idp)
– Resources (FQL guides, context docs)
5. falcon_mcp.client
– OAuth2 token management
– HTTP requests to CrowdStrike Falcon APIs
6. External Service
– CrowdStrike Falcon REST API
b. Relationships & interactions
- User/AI Agent → Transport Adapter → FalconMCPServer
- Server → Registry → Selected Module Handler
- Module Handler → falcon_mcp.client → CrowdStrike API
- Response flows back reverse path
- Server uses common utilities for logging, error handling, JSON utils
c. Architectural patterns & principles
- Plugin architecture for modules (dynamic loading via registry)
- Adapter pattern for transports (stdio, SSE, HTTP)
- Layered separation (Presentation, Application, Domain, Infrastructure)
- Config-driven behavior (command-line args, .env, default modules)
- Strong test coverage with unit and end-to-end tests
d. Key technologies & frameworks
- Python 3.11+, `uv` (MCP runtime), `httpx`/`requests`
- Docker for containerization
- GitHub Actions for CI/CD
- OAuth2 for authentication
- JSON/RPC, SSE, HTTP streaming

##### Detail advice
- Of the eight sample modules as sub-components under “Modules”
- Common utilities (logging, errors, utils) grouped together
- Docker boundary or CI/CD pipeline in a deployment view

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Point & Configuration
    subgraph "Entry Point & Configuration"
        PG["pyproject.toml"]:::util
        DO["Dockerfile"]:::util
        EE[".env.example"]:::util
        ED[".env.dev.example"]:::util
        EP["Entry Point\n(CLI / Docker / Library)"]:::util
    end

    PG --> EP
    DO --> EP
    EE --> EP
    ED --> EP

    %% Transport Layer
    subgraph "Transport Adapters"
        STDIO["stdio Adapter\n(JSON/RPC)"]:::util
        SSE["SSE Adapter\n(EventStream)"]:::util
        HTTP["Streamable HTTP Adapter"]:::util
    end

    EP --> STDIO
    EP --> SSE
    EP --> HTTP
    
    click HTTP "https://github.com/crowdstrike/falcon-mcp/blob/main/tests/test_streamable_http_transport.py"

    STDIO --> SC
    SSE --> SC
    HTTP --> SC

    %% Server Core
    subgraph "FalconMCPServer Core"
        SC["FalconMCPServer\n(server.py)"]:::server
        REG["Module Registry & Dispatcher\n(registry.py)"]:::server
    end

    click SC "https://github.com/crowdstrike/falcon-mcp/blob/main/falcon_mcp/server.py"
    click REG "https://github.com/crowdstrike/falcon-mcp/blob/main/falcon_mcp/registry.py"

    SC --> REG

    %% Common Utilities
    subgraph "Common Utilities"
        AS["API Scopes\n(api_scopes.py)"]:::util
        ERR["Error Handling\n(errors.py)"]:::util
        LOG["Logging\n(logging.py)"]:::util
        UT["Helpers\n(utils.py)"]:::util
    end

    SC --> AS
    SC --> ERR
    SC --> LOG
    SC --> UT

    click AS "https://github.com/crowdstrike/falcon-mcp/blob/main/falcon_mcp/common/api_scopes.py"
    click ERR "https://github.com/crowdstrike/falcon-mcp/blob/main/falcon_mcp/common/errors.py"
    click LOG "https://github.com/crowdstrike/falcon-mcp/blob/main/falcon_mcp/common/logging.py"
    click UT "https://github.com/crowdstrike/falcon-mcp/blob/main/falcon_mcp/common/utils.py"

    %% Module Plugins
    subgraph "Module Plugins"
        BASE["Base Plugin\n(base.py)"]:::modules
        DET["Detections Module\n(detections.py)"]:::modules
        INC["Incidents Module\n(incidents.py)"]:::modules
        INTL["Intel Module\n(intel.py)"]:::modules
        HST["Hosts Module\n(hosts.py)"]:::modules
        SPL["Spotlight Module\n(spotlight.py)"]:::modules
        CLD["Cloud Module\n(cloud.py)"]:::modules
        SU["Sensor Usage Module\n(sensor_usage.py)"]:::modules
        IDP["Identity Protection Module\n(idp.py)"]:::modules
    end

    click BASE "https://github.com/crowdstrike/falcon-mcp/blob/main/falcon_mcp/modules/base.py"
    click DET "https://github.com/crowdstrike/falcon-mcp/blob/main/falcon_mcp/modules/detections.py"
    click INC "https://github.com/crowdstrike/falcon-mcp/blob/main/falcon_mcp/modules/incidents.py"
    click INTL "https://github.com/crowdstrike/falcon-mcp/blob/main/falcon_mcp/modules/intel.py"
    click HST "https://github.com/crowdstrike/falcon-mcp/blob/main/falcon_mcp/modules/hosts.py"
    click SPL "https://github.com/crowdstrike/falcon-mcp/blob/main/falcon_mcp/modules/spotlight.py"
    click CLD "https://github.com/crowdstrike/falcon-mcp/blob/main/falcon_mcp/modules/cloud.py"
    click SU "https://github.com/crowdstrike/falcon-mcp/blob/main/falcon_mcp/modules/sensor_usage.py"
    click IDP "https://github.com/crowdstrike/falcon-mcp/blob/main/falcon_mcp/modules/idp.py"

    REG --> BASE
    REG --> DET
    REG --> INC
    REG --> INTL
    REG --> HST
    REG --> SPL
    REG --> CLD
    REG --> SU
    REG --> IDP

    %% Resources
    subgraph "Resources (Context Docs & FQL Guides)"
        RD_DET["Detections Docs\n(detections.py)"]:::modules
        RD_INC["Incidents Docs\n(incidents.py)"]:::modules
        RD_INTL["Intel Docs\n(intel.py)"]:::modules
        RD_HST["Hosts Docs\n(hosts.py)"]:::modules
        RD_SPL["Spotlight Docs\n(spotlight.py)"]:::modules
        RD_CLD["Cloud Docs\n(cloud.py)"]:::modules
        RD_SU["Sensor Usage Docs\n(sensor_usage.py)"]:::modules
    end

    click RD_DET "https://github.com/crowdstrike/falcon-mcp/blob/main/falcon_mcp/resources/detections.py"
    click RD_INC "https://github.com/crowdstrike/falcon-mcp/blob/main/falcon_mcp/resources/incidents.py"
    click RD_INTL "https://github.com/crowdstrike/falcon-mcp/blob/main/falcon_mcp/resources/intel.py"
    click RD_HST "https://github.com/crowdstrike/falcon-mcp/blob/main/falcon_mcp/resources/hosts.py"
    click RD_SPL "https://github.com/crowdstrike/falcon-mcp/blob/main/falcon_mcp/resources/spotlight.py"
    click RD_CLD "https://github.com/crowdstrike/falcon-mcp/blob/main/falcon_mcp/resources/cloud.py"
    click RD_SU "https://github.com/crowdstrike/falcon-mcp/blob/main/falcon_mcp/resources/sensor_usage.py"

    BASE --> RD_DET
    BASE --> RD_INC
    BASE --> RD_INTL
    BASE --> RD_HST
    BASE --> RD_SPL
    BASE --> RD_CLD
    BASE --> RD_SU

    %% OAuth2 HTTP Client
    CL["OAuth2 HTTP Client\n(client.py)"]:::server
    click CL "https://github.com/crowdstrike/falcon-mcp/blob/main/falcon_mcp/client.py"

    DET --> CL
    INC --> CL
    INTL --> CL
    HST --> CL
    SPL --> CL
    CLD --> CL
    SU --> CL
    IDP --> CL

    %% External Service
    CS["CrowdStrike Falcon REST API"]:::external

    CL -->|"HTTP/REST"| CS

    %% Styling
    classDef server fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef modules fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
    classDef util fill:#D3D3D3,stroke:#333,stroke-width:1px
```
