Bevault Mcp Server

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, 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:

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:

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:

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), 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:

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:

# 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 for monitoring tool executions, errors, and performance.

# 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.

# 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

1. 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.

1. 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.

# 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:

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:

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

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 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
• Source: 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.