# depfac/bevault-mcp-server architecture

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

- Interactive diagram: https://gitdiagram.com/depfac/bevault-mcp-server
- Repository: https://github.com/depfac/bevault-mcp-server

## Overview

beVault MCP exposes beVault’s Build, Source, and Distribute operations, with optional OIDC-protected States operations. An MCP client invokes registered tools; the tools use domain clients to call the corresponding beVault APIs and return tool responses. The graph groups documented capabilities even where individual tool implementations were not sampled; those edges are documented at the README level rather than inferred from filenames.

Main entry points: [`bevault_mcp/metavault/client/__init__.py`](https://github.com/depfac/bevault-mcp-server/blob/main/bevault_mcp/metavault/client/__init__.py) (MetaVault facade), [`bevault_mcp/main.py`](https://github.com/depfac/bevault-mcp-server/blob/main/bevault_mcp/main.py) (MCP server), [`bevault_mcp/metavault/client/source_systems.py`](https://github.com/depfac/bevault-mcp-server/blob/main/bevault_mcp/metavault/client/source_systems.py) (Source client), [`bevault_mcp/states/tools`](https://github.com/depfac/bevault-mcp-server/tree/main/bevault_mcp/states/tools) (Execution and store tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["MCP runtime"]
  node_server["MCP server<br/>[main.py]"]
  node_settings["Settings and auth<br/>[config.py]"]
end

subgraph group_metavault["MetaVault"]
  node_mvtools["Build tools"]
  node_sourcetools["Source tools"]
  node_marttools["Distribute tools"]
  node_searchtool["Model search<br/>[search.py]"]
  node_mappingtool["Mapping tools<br/>[mappings.py]"]
  node_mvclient["MetaVault facade<br/>[__init__.py]"]
  node_modelclient["Model client<br/>[model.py]"]
  node_sourceclient["Source client<br/>[source_systems.py]"]
  node_mappingclient["Mapping client<br/>[mappings.py]"]
  node_martclient["Information mart client"]
  node_projectclient["Project client<br/>[projects.py]"]
end

subgraph group_states["States"]
  node_statesmachines["State machine tools<br/>[state_machines.py]"]
  node_statestools["Execution and store tools"]
  node_statesclient["States clients"]
end

subgraph group_contracts["API contracts and HTTP"]
  node_contracts["Request and response models"]
  node_statesmodels["States models"]
  node_http["HTTP transport<br/>[http.py]"]
end

node_user(("MCP client"))
node_metavaultapi{{"MetaVault API"}}
node_statesapi{{"States API"}}

node_user -->|"invokes tools"| node_server
node_server -->|"loads configuration"| node_settings
node_server -->|"initializes client"| node_mvclient
node_server -->|"initializes client"| node_statesclient
node_server -->|"registers tools"| node_mvtools
node_server -->|"registers tools"| node_statestools
node_mvtools -->|"performs operations"| node_metavaultapi
node_sourcetools -->|"manages sources"| node_metavaultapi
node_marttools -->|"manages marts"| node_metavaultapi
node_searchtool -->|"searches model"| node_mvclient
node_mappingtool -->|"uses client"| node_mvclient
node_mvclient -->|"provides resource"| node_modelclient
node_mvclient -->|"provides resource"| node_sourceclient
node_mvclient -->|"provides resource"| node_mappingclient
node_mvclient -->|"provides resource"| node_martclient
node_mvclient -->|"provides resource"| node_projectclient
node_modelclient -->|"calls API"| node_metavaultapi
node_sourceclient -->|"calls API"| node_metavaultapi
node_mappingclient -->|"calls API"| node_metavaultapi
node_martclient -->|"calls API"| node_metavaultapi
node_statesmachines -->|"uses client"| node_statesclient
node_statestools -->|"orchestrates states"| node_statesapi
node_statesclient -->|"calls API"| node_statesapi
node_searchtool -->|"uses models"| node_contracts
node_mappingtool -->|"uses mapping models"| node_contracts
node_statesmachines -->|"uses models"| node_statesmodels
node_statestools -->|"formats responses"| node_statesmodels
node_sourceclient -->|"uses HTTP verbs"| node_http
node_metavaultapi -.->|"returns results"| node_user

click node_server "https://github.com/depfac/bevault-mcp-server/blob/main/bevault_mcp/main.py"
click node_settings "https://github.com/depfac/bevault-mcp-server/blob/main/bevault_mcp/config.py"
click node_mvtools "https://github.com/depfac/bevault-mcp-server/tree/main/bevault_mcp/metavault/tools"
click node_sourcetools "https://github.com/depfac/bevault-mcp-server/tree/main/bevault_mcp/metavault/tools"
click node_marttools "https://github.com/depfac/bevault-mcp-server/tree/main/bevault_mcp/metavault/tools"
click node_searchtool "https://github.com/depfac/bevault-mcp-server/blob/main/bevault_mcp/metavault/tools/search.py"
click node_mappingtool "https://github.com/depfac/bevault-mcp-server/blob/main/bevault_mcp/metavault/tools/mappings.py"
click node_mvclient "https://github.com/depfac/bevault-mcp-server/blob/main/bevault_mcp/metavault/client/__init__.py"
click node_modelclient "https://github.com/depfac/bevault-mcp-server/blob/main/bevault_mcp/metavault/client/model.py"
click node_sourceclient "https://github.com/depfac/bevault-mcp-server/blob/main/bevault_mcp/metavault/client/source_systems.py"
click node_mappingclient "https://github.com/depfac/bevault-mcp-server/blob/main/bevault_mcp/metavault/client/mappings.py"
click node_martclient "https://github.com/depfac/bevault-mcp-server/blob/main/bevault_mcp/metavault/client/information_marts.py"
click node_projectclient "https://github.com/depfac/bevault-mcp-server/blob/main/bevault_mcp/metavault/client/projects.py"
click node_statesmachines "https://github.com/depfac/bevault-mcp-server/blob/main/bevault_mcp/states/tools/state_machines.py"
click node_statestools "https://github.com/depfac/bevault-mcp-server/tree/main/bevault_mcp/states/tools"
click node_statesclient "https://github.com/depfac/bevault-mcp-server/tree/main/bevault_mcp/states/client"
click node_contracts "https://github.com/depfac/bevault-mcp-server/tree/main/bevault_mcp/metavault/models"
click node_statesmodels "https://github.com/depfac/bevault-mcp-server/tree/main/bevault_mcp/states/models"
click node_http "https://github.com/depfac/bevault-mcp-server/blob/main/bevault_mcp/shared/http.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_settings,node_user toneBlue
class node_mvtools,node_sourcetools,node_marttools,node_searchtool,node_mappingtool,node_mvclient,node_modelclient,node_sourceclient,node_mappingclient,node_martclient,node_projectclient toneAmber
class node_statesmachines,node_statestools,node_statesclient,node_metavaultapi,node_statesapi toneMint
class node_contracts,node_statesmodels,node_http toneRose
```

## Components

### MCP runtime

- [MCP server](https://github.com/depfac/bevault-mcp-server/blob/main/bevault_mcp/main.py): `bevault_mcp/main.py`
- [Settings and auth](https://github.com/depfac/bevault-mcp-server/blob/main/bevault_mcp/config.py): `bevault_mcp/config.py`

### MetaVault

- [Build tools](https://github.com/depfac/bevault-mcp-server/tree/main/bevault_mcp/metavault/tools): `bevault_mcp/metavault/tools`
- [Source tools](https://github.com/depfac/bevault-mcp-server/tree/main/bevault_mcp/metavault/tools): `bevault_mcp/metavault/tools`
- [Distribute tools](https://github.com/depfac/bevault-mcp-server/tree/main/bevault_mcp/metavault/tools): `bevault_mcp/metavault/tools`
- [Model search](https://github.com/depfac/bevault-mcp-server/blob/main/bevault_mcp/metavault/tools/search.py): `bevault_mcp/metavault/tools/search.py`
- [Mapping tools](https://github.com/depfac/bevault-mcp-server/blob/main/bevault_mcp/metavault/tools/mappings.py): `bevault_mcp/metavault/tools/mappings.py`
- [MetaVault facade](https://github.com/depfac/bevault-mcp-server/blob/main/bevault_mcp/metavault/client/__init__.py): `bevault_mcp/metavault/client/__init__.py`
- [Model client](https://github.com/depfac/bevault-mcp-server/blob/main/bevault_mcp/metavault/client/model.py): `bevault_mcp/metavault/client/model.py`
- [Source client](https://github.com/depfac/bevault-mcp-server/blob/main/bevault_mcp/metavault/client/source_systems.py): `bevault_mcp/metavault/client/source_systems.py`
- [Mapping client](https://github.com/depfac/bevault-mcp-server/blob/main/bevault_mcp/metavault/client/mappings.py): `bevault_mcp/metavault/client/mappings.py`
- [Information mart client](https://github.com/depfac/bevault-mcp-server/blob/main/bevault_mcp/metavault/client/information_marts.py): `bevault_mcp/metavault/client/information_marts.py`
- [Project client](https://github.com/depfac/bevault-mcp-server/blob/main/bevault_mcp/metavault/client/projects.py): `bevault_mcp/metavault/client/projects.py`

### States

- [State machine tools](https://github.com/depfac/bevault-mcp-server/blob/main/bevault_mcp/states/tools/state_machines.py): `bevault_mcp/states/tools/state_machines.py`
- [Execution and store tools](https://github.com/depfac/bevault-mcp-server/tree/main/bevault_mcp/states/tools): `bevault_mcp/states/tools`
- [States clients](https://github.com/depfac/bevault-mcp-server/tree/main/bevault_mcp/states/client): `bevault_mcp/states/client`

### API contracts and HTTP

- [Request and response models](https://github.com/depfac/bevault-mcp-server/tree/main/bevault_mcp/metavault/models): `bevault_mcp/metavault/models`
- [States models](https://github.com/depfac/bevault-mcp-server/tree/main/bevault_mcp/states/models): `bevault_mcp/states/models`
- [HTTP transport](https://github.com/depfac/bevault-mcp-server/blob/main/bevault_mcp/shared/http.py): `bevault_mcp/shared/http.py`

### Other components

- **MCP client**
- **MetaVault API**
- **States API**

## Connections

- MCP client → MCP server: invokes tools (evidence: `README.md`)
- MCP server → Settings and auth: loads configuration (evidence: `bevault_mcp/main.py`)
- MCP server → MetaVault facade: initializes client (evidence: `bevault_mcp/main.py`)
- MCP server → States clients: initializes client (evidence: `bevault_mcp/main.py`)
- MCP server → Build tools: registers tools (evidence: `bevault_mcp/main.py`)
- MCP server → Execution and store tools: registers tools (evidence: `bevault_mcp/main.py`)
- Build tools → MetaVault API: performs operations (evidence: `README.md`)
- Source tools → MetaVault API: manages sources (evidence: `README.md`)
- Distribute tools → MetaVault API: manages marts (evidence: `README.md`)
- Model search → MetaVault facade: searches model (evidence: `bevault_mcp/metavault/tools/search.py`)
- Mapping tools → MetaVault facade: uses client (evidence: `bevault_mcp/metavault/tools/mappings.py`)
- MetaVault facade → Model client: provides resource (evidence: `bevault_mcp/metavault/client/__init__.py`)
- MetaVault facade → Source client: provides resource (evidence: `bevault_mcp/metavault/client/__init__.py`)
- MetaVault facade → Mapping client: provides resource (evidence: `bevault_mcp/metavault/client/__init__.py`)
- MetaVault facade → Information mart client: provides resource (evidence: `bevault_mcp/metavault/client/__init__.py`)
- MetaVault facade → Project client: provides resource (evidence: `bevault_mcp/metavault/client/__init__.py`)
- Model client → MetaVault API: calls API (evidence: `README.md`)
- Source client → MetaVault API: calls API (evidence: `bevault_mcp/metavault/client/source_systems.py`)
- Mapping client → MetaVault API: calls API (evidence: `README.md`)
- Information mart client → MetaVault API: calls API (evidence: `README.md`)
- State machine tools → States clients: uses client (evidence: `bevault_mcp/states/tools/state_machines.py`)
- Execution and store tools → States API: orchestrates states (evidence: `README.md`)
- States clients → States API: calls API (evidence: `README.md`)
- Model search → Request and response models: uses models (evidence: `bevault_mcp/metavault/tools/search.py`)
- Mapping tools → Request and response models: uses mapping models (evidence: `bevault_mcp/metavault/tools/mappings.py`)
- State machine tools → States models: uses models (evidence: `bevault_mcp/states/tools/state_machines.py`)
- Execution and store tools → States models: formats responses (evidence: `bevault_mcp/states/tools/executions.py`)
- Source client → HTTP transport: uses HTTP verbs
- MetaVault API → MCP client: returns results