# Bevault Mcp Server

> beVault MCP server

- **Type:** MCP server
- **Install:** `agentstack add mcp-depfac-bevault-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [depfac](https://agentstack.voostack.com/s/depfac)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [depfac](https://github.com/depfac)
- **Source:** https://github.com/depfac/bevault-mcp-server
- **Website:** https://support.bevault.io/en/bevault-documentation/current-version/bevault-mcp-server

## Install

```sh
agentstack add mcp-depfac-bevault-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# bevault-mcp

## Table of Contents

- [Introduction](#introduction)
- [Features](#features)
- [Installation](#installation)
  - [Development Setup](#development-setup)
  - [Production Setup](#production-setup)
- [Configuration](#configuration)
  - [Environment Variables](#environment-variables)
  - [Sentry Monitoring](#sentry-monitoring)
  - [OpenTelemetry Tracing](#opentelemetry-tracing)
  - [Authentication](#authentication)
  - [OIDC Configuration](#oidc-configuration)
  - [OAuth Client Storage (OIDC)](#oauth-client-storage-oidc)
  - [CORS for Browser-Based OIDC Clients](#cors-for-browser-based-oidc-clients)
- [Run](#run)
- [Using with n8n](#using-with-n8n)
- [Development](#development)
- [Contributing](#contributing)
- [License](#license)

## Introduction

This is the MCP (Model Context Protocol) server for [beVault](https://www.bevault.io/), a modern data platform designed to manage scalable, secure, and auditable data using Data Vault methodology.

This MCP server allows you to perform actions that users can do in the following beVault modules:
- **Build**: Create and manage data models (Hubs, Links, Satellites, Reference Tables)
- **Source**: Manage source systems, data packages, and staging tables
- **Distribute**: Create and manage information marts and their scripts
- **States** (optional): Orchestrate state machines and executions — requires OIDC

> **Note**: Support for the **Verify** module will be added in a future release.

> **v1.1.0 Migration**: With version v1.1.0 of this project, we migrated to FastMCP v3 which no longer supports the `Authorization` header to pass the beVault API token. As of v1.1.0, make sure to use the new `bevault-api-key` header in your MCP client to pass your beVault API token.

The server exposes tools to interact with beVault's API using FastMCP with HTTP transport.

## Features
- `search_model`: search entities (Hubs, Links, Satellites, ReferenceTables) in a beVault project
- `search_information_marts`: search and list information marts (with simplified script info)
- `get_information_mart_script`: retrieve full information mart script definition (metadata + columns + sources)
- `search_source_systems`: search source systems and their data packages (with staging table info)
- `create_*` / `update_*` / `delete_*` tools for hubs, links, source systems, data packages, information marts and scripts
- `create_staging_table` and column tools to define and evolve staging tables
- Mapping tools (`map_column_to_hub`, `map_columns_to_link`, `map_columns_to_satellite`, delete/update mapping helpers)
- Introspection tools like `get_link`, `get_satellite`, `get_staging_table`, `get_snapshots`
- **States** (requires OIDC): `list_state_machines`, `get_state_machine`, `create_state_machine`, `update_state_machine`, `delete_state_machine`, `list_executions`, `get_execution`, `start_execution`

## Installation

### Development Setup

For development, you can set up the project locally:

1. **Download the code** from the repository
2. **Install Python** (Python >= 3.13 required)
3. **Install dependencies** from `requirements.txt`:
   ```bash
   pip install -r requirements.txt
   ```

### Production Setup

For production, you can use Docker and docker-compose. The project uses our own registry:

**Docker Image**: `quay.io/dfakto_org/bevault_mcp`

You can pull and run the image directly:
```bash
docker pull quay.io/dfakto_org/bevault_mcp
docker run -e BEVAULT_BASE_URL= -e REQUEST_TIMEOUT_SECONDS=30 quay.io/dfakto_org/bevault_mcp
```

**Quick deployment with Docker Compose**

Create a `docker-compose.yml` file:

```yaml
services:
  bevault-mcp:
    container_name: bevault-mcp
    image: quay.io/dfakto_org/bevault_mcp:v1.0.0
    environment:
      BEVAULT_BASE_URL: "https://bevault.your.domain"
      REQUEST_TIMEOUT_SECONDS: "30"
      MCP_HOST: 0.0.0.0
      MCP_PORT: "8000"
      # Persist OAuth client registrations (required when using OIDC)
      FASTMCP_HOME: /data/fastmcp
      # OIDC variables (when enabled)
      # OIDC_CONFIG_URL: ...
      # OIDC_CLIENT_ID: ...
      # OIDC_CLIENT_SECRET: ...
      # OIDC_BASE_URL: ...
    volumes:
      - bevault-mcp-data:/data/fastmcp
    ports:
      - "8000:8000"
    restart: always

volumes:
  bevault-mcp-data:
```

Then run:
```bash
docker compose up -d
```

The MCP server will be available at `http://localhost:8000/mcp`. Remember to replace `https://bevault.your.domain` with your actual beVault instance URL.

> **Deploying alongside beVault**: If you run the MCP server in the same docker-compose stack as beVault (see [Production deployment](https://support.bevault.io/en/bevault-documentation/current-version/architecture-installation/deployment/production-deployment)), you can set `BEVAULT_BASE_URL` to the **metavault-ui** service name instead of an external URL (e.g. `http://metavault-ui:80`). This is required because the MCP tools call the `/metavault` routes, which are served by the embedded reverse proxy of the metavault-ui front-end application.

## Configuration

### Deployment Modes

The server supports three deployment modes via module toggles. At least one module must be enabled.

| Mode | Configuration | Tools |
|------|---------------|-------|
| MetaVault only (default) | `METAVAULT_ENABLED=true`, `STATES_ENABLED=false` | Build, Source, Distribute |
| States only | `METAVAULT_ENABLED=false`, `STATES_ENABLED=true` | States |
| Both | both `true` | MetaVault + States |

**Auth by mode:**

| Mode | MetaVault tools | States tools |
|------|-----------------|--------------|
| API key only | Available | Not registered |
| OIDC | Available | Available when `STATES_ENABLED=true` |

States requires OIDC — the States API does not accept the `bevault-api-key` header. A States-only deployment must have OIDC configured.

**States-only example:**

```ini
METAVAULT_ENABLED=false
STATES_ENABLED=true
STATES_BASE_URL=https://states.your.domain
REQUEST_TIMEOUT_SECONDS=30
# OIDC variables required (see OIDC Configuration below)
```

### Environment Variables

Create a `.env` file in the project root or set these environment variables:

```ini
# MetaVault-only (default deployment)
METAVAULT_ENABLED=true
STATES_ENABLED=false
BEVAULT_BASE_URL=https://bevault.metavault.url.com
REQUEST_TIMEOUT_SECONDS=30
MCP_HOST=0.0.0.0
MCP_PORT=8000
```

**Required Variables (MetaVault mode, default):**
- `BEVAULT_BASE_URL`: The URL of your beVault MetaVault instance (required when `METAVAULT_ENABLED=true`)
- `REQUEST_TIMEOUT_SECONDS`: Number of seconds after which requests to beVault's API will timeout

**Required Variables (States mode):**
- `STATES_BASE_URL`: The URL of your beVault States API (required when `STATES_ENABLED=true`)
- OIDC configuration (required for States-only; see [OIDC Configuration](#oidc-configuration))

**Module Toggles (optional):**
- `METAVAULT_ENABLED`: Enable MetaVault tools (default: `true`)
- `STATES_ENABLED`: Enable States module (default: `false`)

**Optional Variables:**
- `MCP_HOST`: The host address on which the MCP server will run (optional, default: `0.0.0.0`)
- `MCP_PORT`: The port on which the MCP server will run (optional, default: `8000`)
- `FASTMCP_HOME`: Data directory for FastMCP (optional; defaults to the platform user data directory). Set explicitly when using OIDC in Docker or for local persistence—see [OAuth Client Storage (OIDC)](#oauth-client-storage-oidc)
- `CORS_ORIGINS`: Comma-separated allowed origins for CORS (optional; required for browser-based OIDC clients—see [CORS for Browser-Based OIDC Clients](#cors-for-browser-based-oidc-clients))

### Sentry Monitoring

Sentry integration is optional. When `SENTRY_DSN` is set, the server initializes Sentry with the [MCP integration](https://docs.sentry.io/platforms/python/integrations/mcp/) for monitoring tool executions, errors, and performance.

```ini
# Sentry (optional - unset or leave empty to disable)
SENTRY_DSN=https://your-dsn@sentry.io/project-id
SENTRY_ENVIRONMENT=production
SENTRY_TRACES_SAMPLE_RATE=1.0
SENTRY_SEND_DEFAULT_PII=false
SENTRY_SERVER_NAME=bevault-mcp-prod
SENTRY_DEFAULTTAGS__service=bevault-mcp
SENTRY_DEFAULTTAGS__deployment=prod
```

| Variable | Default | Description |
|----------|---------|-------------|
| `SENTRY_DSN` | — | Sentry project DSN; required to enable Sentry |
| `SENTRY_ENVIRONMENT` | `production` | Environment name for grouping in Sentry |
| `SENTRY_TRACES_SAMPLE_RATE` | `1.0` | Fraction of transactions to trace (0.0–1.0) |
| `SENTRY_SEND_DEFAULT_PII` | `false` | Include tool inputs/outputs (PII) in events |
| `SENTRY_DEBUG` | `false` | Enable Sentry SDK debug logging |
| `SENTRY_INCLUDE_PROMPTS` | `true` | Include prompt/tool data in spans (when PII enabled) |
| `SENTRY_SERVER_NAME` | — | Server instance identifier |
| `SENTRY_DEFAULTTAGS__[key]` | — | Default tags, e.g. `SENTRY_DEFAULTTAGS__service=bevault-mcp` |

### OpenTelemetry Tracing

OpenTelemetry tracing is optional. When `OTEL_EXPORTER_OTLP_ENDPOINT` is set, the server exports traces to an OTLP collector. Compatible with Jaeger, Zipkin, Grafana Tempo, Datadog, and other OTLP backends.

```ini
# OpenTelemetry (optional - unset or leave empty to disable)
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
OTEL_SERVICE_NAME=bevault-mcp
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
```

| Variable | Default | Description |
|----------|---------|-------------|
| `OTEL_EXPORTER_OTLP_ENDPOINT` | — | OTLP collector endpoint; required to enable tracing |
| `OTEL_SERVICE_NAME` | `bevault-mcp` | Service name in traces |

### Authentication

The MCP server supports two authentication modes. The mode is determined by whether OIDC environment variables are set.

#### API Key Mode (default)

When OIDC variables are **not** configured, the MCP server requires the `bevault-api-key` header. All requests use a single beVault API token, and **all users inherit the rights of that API key**.

1. **Create an API token** in beVault following the [beVault API Keys documentation](https://support.bevault.io/en/bevault-documentation/current-version/reference-guide/datafactory-user-reference-guide/datafactory-modules/client-admin/api-keys)

2. **Configure your MCP client** to include the following header in all requests:
   ```
   bevault-api-key: [your-api-token]
   ```
   Replace `[your-api-token]` with the actual API token you created.

3. The MCP server forwards this token to beVault's API for authentication.

**Important**: The permissions and project access assigned to your API token determine what operations the MCP server can perform. Make sure to configure the API key with appropriate rights for the projects and modules you need to access.

#### OIDC Mode

When OIDC variables are configured, the MCP server uses your OIDC provider for authentication. **End users are asked to authenticate themselves**, and each user inherits **beVault's rights of the authenticated user**. The MCP server and beVault must use the same OIDC provider so that the Bearer token issued for the MCP server is also accepted by beVault.

When the States module is enabled, the same Bearer token must also be accepted by the States API (compatible audience/realm).

Configure the following environment variables (see [OIDC configuration](#oidc-configuration) below). The MCP client will direct users through the OIDC flow; after authentication, the Bearer token is sent on each request and forwarded to beVault and States APIs.

For **browser-based clients** (e.g., web apps using the MCP server), configure `CORS_ORIGINS` so the OIDC redirect flow can complete. See [CORS for Browser-Based OIDC Clients](#cors-for-browser-based-oidc-clients).

### OIDC Configuration

When all required OIDC variables are set, OIDC authentication is enabled. Leave them unset to use API key mode. Required scopes default to `openid,profile` (required by MetaVault); set `OIDC_REQUIRED_SCOPES` only to override.

```ini
# OIDC (optional - unset or leave empty to use bevault-api-key instead)
OIDC_CONFIG_URL=https://your-oidc-provider.com/.well-known/openid-configuration
OIDC_CLIENT_ID=your-client-id
OIDC_CLIENT_SECRET=your-client-secret
OIDC_BASE_URL=https://your-mcp-server.domain.com
OIDC_AUDIENCE=optional-audience
OIDC_REDIRECT_PATH=/optional-redirect-path
# OIDC_REQUIRED_SCOPES=openid,profile,email  # optional override
```

| Variable | Required | Description |
|----------|----------|-------------|
| `OIDC_CONFIG_URL` | Yes* | OpenID Connect discovery URL (e.g. `/.well-known/openid-configuration`) |
| `OIDC_CLIENT_ID` | Yes* | OAuth client ID registered with the OIDC provider |
| `OIDC_CLIENT_SECRET` | Yes* | OAuth client secret |
| `OIDC_BASE_URL` | Yes* | Public URL of this MCP server (used for OAuth redirects) |
| `OIDC_AUDIENCE` | No | Token audience if required by your provider |
| `OIDC_REDIRECT_PATH` | No | Custom OAuth redirect path |
| `OIDC_REQUIRED_SCOPES` | No | Optional override for required scopes; defaults to `openid,profile` |

\*All four (`OIDC_CONFIG_URL`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`, `OIDC_BASE_URL`) must be set for OIDC to be enabled.

### OAuth Client Storage (OIDC)

When OIDC is enabled, MCP clients register dynamically with the server (Dynamic Client Registration). These registrations—and related OAuth state such as upstream tokens and authorization codes—must persist across server restarts.

**API key mode does not use client storage**—this section applies only when OIDC is enabled.

#### Docker

Mount a named volume at `FASTMCP_HOME` so client registrations survive container recreate and redeploy. The [Docker Compose example](#production-setup) above shows the recommended setup:

```yaml
environment:
  FASTMCP_HOME: /data/fastmcp
volumes:
  - bevault-mcp-data:/data/fastmcp
```

#### Local development

For local persistence, set `FASTMCP_HOME` to a project-local directory (e.g. `./.fastmcp`).

#### Production notes

- Keep `OIDC_CLIENT_SECRET` stable across redeploys. FastMCP derives the JWT signing key and storage encryption key from it; changing the secret invalidates stored OAuth state and forces clients to re-register.

### CORS for Browser-Based OIDC Clients

When using OIDC with browser-based MCP clients (e.g., web UIs that connect to this server), the OAuth redirect flow requires CORS to be configured. Set `CORS_ORIGINS` to the origin(s) of your client application:

```ini
CORS_ORIGINS=https://your-web-app.domain.com,https://another-origin.com
```

| Variable | Default | Description |
|----------|---------|-------------|
| `CORS_ORIGINS` | — | Comma-separated list of allowed origins (e.g. `https://app.example.com`). When set, CORS middleware is enabled with `Authorization` and `Content-Type` in allowed headers. Required for browser-based OIDC clients. |

## Run

```bash
python -m bevault_mcp.main
```

The server will start an HTTP MCP server accessible at `http://localhost:8000/mcp`.

## Using with n8n

For a complete guide on integrating the beVault MCP server with n8n—including installation, API key setup, workflow configuration, and system prompts—see the [How to use beVault MCP Server with n8n](https://support.bevault.io/en/bevault-documentation/current-version/bevault-mcp-server/how-to-use-bevault-mcp-server-with-n8n) documentation.

## Development
- Code style and linting: ruff (see `CONTRIBUTING.md` for details)
- Python >= 3.13
- Uses FastMCP for HTTP/Streamable transport support

## Contributing

Contributions to this project are welcome! Please read the [CONTRIBUTING.md](CONTRIBUTING.md) guide for details on development setup, code style, pre-commit hooks, and how to submit changes.

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [depfac](https://github.com/depfac)
- **Source:** [depfac/bevault-mcp-server](https://github.com/depfac/bevault-mcp-server)
- **License:** MIT
- **Homepage:** https://support.bevault.io/en/bevault-documentation/current-version/bevault-mcp-server

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-depfac-bevault-mcp-server
- Seller: https://agentstack.voostack.com/s/depfac
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.