Bevault

Table of Contents

• Introduction
• Features
• Installation
  • Development Setup
  • Production Setup
• Configuration
  • Environment Variables
  • Sentry Monitoring
  • OpenTelemetry Tracing
  • Authentication
  • OIDC Configuration
  • OAuth Client Storage (OIDC)
  • CORS for Browser-Based OIDC Clients
• Run
• Using with n8n
• Development
• Contributing
• 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.

Compatibility: Hub/link create and update tools, and satellite mapping tools, require beVault 3.12+ because they send the required businessName / satelliteBusinessName fields. Technical names remain constrained (hub: 25, link: 35, satellite: 20 characters; letters, digits, and underscores only).

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:

   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=<your-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)

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)
• CORS_ORIGINS: Comma-separated allowed origins for CORS (optional; required for browser-based OIDC clients—see 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://[email protected]/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

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

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 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
• Run unit tests with pytest

Contributing

Contributions to this project are welcome! Please read the 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 file for details.