MDDB Configuration Reference

Complete reference for all MDDB configuration parameters.

Precedence order: CLI flags > environment variables > YAML config file > defaults

Table of Contents

• General / Core
• HTTP Server
• gRPC Server
• MCP (Model Context Protocol)
• HTTP/3 (QUIC)
• Authentication
• Embedding / Vector Search
• Vector Index
• Full-Text Search (FTS)
• Temporal Tracking
• Spell Correction
• Compression
• Replication
• Automation & Triggers
• GraphQL
• CLI Flags
• YAML Config File

General / Core

HTTP Server

gRPC Server

MCP (Model Context Protocol)

MCP API Key Authentication

MCP Rate Limiting

MCP Logging

HTTP/3 (QUIC)

Authentication

Incident Events (ISO 27001 / SOC 2)

Security and operational incidents are delivered through the existing /v1/webhooks subscription system. A webhook that registers for one of the incident event names receives the same JSON envelope as document-lifecycle events, with the event-specific payload in detail.

Registering a webhook for incident events:

curl -X POST localhost:11023/v1/webhooks \ -H "Content-Type: application/json" \ -d '{ "url": "https://ops.example.com/mddb-incidents", "events": ["security.auth_failure_burst","ops.panic_recovered","ops.disk_usage_high"] }'

Retries, backoff (0s / 1s / 5s / 15s) and X-MDDB-Event / X-MDDB-Webhook-ID headers are shared with the existing document-lifecycle delivery path.

At-Rest Encryption (ISO 27001 / SOC 2)

Opt-in per-collection AES-256-GCM encryption for documents and revisions. Activation requires both a process-wide key and a per-collection flag — an operator who does neither pays zero runtime cost and stores plaintext like today.

Enabling encryption for a collection:

curl -X PUT localhost:11023/v1/collection-config \ -H "Authorization: Bearer $ADMIN_JWT" \ -d '{"collection":"secrets","encrypted":true}'

Details:

• Wire format per stored value: MDDB_ENC_V1\x00 (12 B magic) + 12 B nonce + AES-256-GCM ciphertext & auth tag.
• Backward compat: legacy plaintext documents remain readable even after a collection is flipped to encrypted=true. New writes use ciphertext, old reads transparently passthrough because the magic prefix is absent.
• Scope: only the docs and rev buckets carry ciphertext. FTS inverted indexes and vector embeddings remain plaintext because they are queryable structures — encrypting them would break search. Document this in your threat model.
• Key loss is terminal: losing MDDB_ENCRYPTION_KEY makes the corresponding collections unrecoverable. Store the key in an HSM / secret manager and keep an offline escrow.
• Startup safety: if a collection has encrypted=true but MDDB_ENCRYPTION_KEY is missing, the server refuses to start — writing plaintext into a collection that claims to be encrypted is treated as a compliance failure, not a warning.
• Bootstrap key: openssl rand -base64 32.

Generate a fresh key:

export MDDB_ENCRYPTION_KEY="$(openssl rand -base64 32)"

Key Rotation (2.9.16+)

The 2.9.16 wire format V2 prefixes every ciphertext with a 1-byte keyID so the encryptor can hold a primary plus any number of read-only previous keys. V1 (2.9.15) ciphertexts continue to decrypt — non-breaking upgrade.

Rotation procedure:

old_key="$MDDB_ENCRYPTION_KEY"
old_id="${MDDB_ENCRYPTION_KEY_ID:-1}" export MDDB_ENCRYPTION_KEY="$(openssl rand -base64 32)"
export MDDB_ENCRYPTION_KEY_ID=2 export MDDB_ENCRYPTION_KEYS_PREVIOUS="[{\"id\":$old_id,\"key\":\"$old_key\"}]" curl -X POST localhost:11023/v1/encryption/rotate \ -H "Authorization: Bearer $ADMIN_JWT" \ -d '{"collection":""}' # empty = all collections curl localhost:11023/v1/encryption/status -H "Authorization: Bearer $ADMIN_JWT" unset MDDB_ENCRYPTION_KEYS_PREVIOUS

The admin panel exposes the same workflow under Sidebar → Encryption: keyID, per-collection coverage, "Start rotation" button, and a job table.

Audit Log Export (ISO 27001 / SOC 2)

The audit log persists locally to BoltDB by default. For tamper-evident, off-host retention (the auditor expectation), mirror events to an external SIEM webhook or a syslog collector. Local BoltDB remains the source of truth — exporters are best-effort.

Both sinks can run together; per-sink delivery counters are exposed at GET /v1/audit/exporters and rendered in the Security panel.

Quick recipe — Splunk HEC + papertrail-style syslog:

export MDDB_AUDIT_ENABLED=true
export MDDB_AUDIT_EXPORT_WEBHOOK_URL="https://splunk.example/services/collector/raw"
export MDDB_AUDIT_EXPORT_WEBHOOK_HEADER="Authorization: Splunk $HEC_TOKEN"
export MDDB_AUDIT_EXPORT_SYSLOG_ADDR="tcp://logs.papertrailapp.com:12345"

Backup Path Jail (2.9.16+)

/v1/backup and /v1/restore accept a user-supplied path. Without bounds an admin (or an attacker who steals admin creds) could read or overwrite arbitrary files. The 2.9.16 jail confines every backup to a single directory.

No further configuration required — the jail is always on.

Production Hardening (ISO 27001 / SOC 2)

MDDB_PRODUCTION=true is a single switch that fails the server start unless every ISO 27001 / SOC 2 guardrail is satisfied. When unset, the guard logs a one-line warning at boot and continues with the same defaults as before — so existing deployments are unaffected.

On a successful production start the server logs:

✓ Production guards satisfied (ISO 27001 / SOC 2)

When a requirement is missing, startup is aborted with a line-by-line breakdown pointing at each offending env var.

Rate Limiting (HTTP + gRPC)

Shared sliding-window limiter covering both HTTP and gRPC. Separate from the pre-existing MDDB_MCP_RATE_LIMIT_* budget, which continues to apply to the MCP endpoints only.

HTTP responses carry X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset; rejected requests get 429 Too Many Requests with Retry-After. gRPC rejects with codes.ResourceExhausted. The paths /health, /v1/health, and /metrics are always exempt so monitoring and load-balancer probes never trip the limiter.

Audit Log (ISO 27001 / SOC 2)

Structured authentication and mutation trail persisted to a dedicated audit BoltDB bucket. Events are buffered and flushed asynchronously so hot-path handlers never block on disk I/O. Queryable via admin-only GET /v1/audit.

Query parameters on GET /v1/audit: from / to (RFC3339) or fromNanos / toNanos, actor, action, result (ok/fail), limit (default 100). Response shape: {events: [...], count, dropped} — dropped counts events lost when the in-memory buffer was full.

Embedding / Vector Search

Provider Defaults

Vector Index

MCP Server Info

Customize the MCP server profile returned in the initialize response. Useful for identifying your server to LLM clients.

Or via YAML config:

mcp: serverInfo: name: "my-knowledge-base" description: "Company internal documentation" vendor: "Acme Corp" homepage: "https://docs.acme.com" instructions: | This is the company knowledge base. Use search_documents to find relevant articles before answering questions. Always cite document keys in your responses. Prefer the 'docs' collection for technical questions and 'blog' for product updates.

Server-Sent Events (SSE)

TLS / HTTPS / mTLS

See TLS.md for the full setup guide (cert generation, recipes, troubleshooting).

MinVersion is pinned to TLS 1.2. mTLS is automatically skipped on UDS listeners (filesystem permissions already authenticate the local peer).

Unix Domain Socket transport

MDDB_HTTP_ADDR and MDDB_GRPC_ADDR accept either a TCP host:port (default) or a Unix Domain Socket address of the form unix:/absolute/path.sock. The server creates the socket with owner-only 0600 permissions, removes any stale socket file from a previous run, and unlinks the socket on graceful shutdown.

MDDB_HTTP_ADDR=unix:/var/run/mddb/http.sock \
MDDB_GRPC_ADDR=:11024 \
./mddbd

TLS is automatically disabled on UDS listeners (peer is authenticated by filesystem permissions; API keys / JWT still apply on top). Per-IP rate limits in SSE collapse to a single bucket on UDS — apply application-level rate limiting if you need to differentiate clients.

Clients with native UDS support:

Profiling

HTTP Connection Pool

Full-Text Search (FTS)

Temporal Tracking

When enabled, provides endpoints: POST /v1/temporal/query, POST /v1/temporal/hot, POST /v1/temporal/histogram. Per-collection opt-in via Collection Settings (trackAccess, trackHot).

Spell Correction

When enabled, provides endpoints: POST /v1/spell-suggest, POST /v1/spell-cleanup, GET/PUT/DELETE /v1/spell-dictionary. Enable spellCorrect: true on a collection for auto-correction.

Compression

Replication

Automation & Triggers

GraphQL

Per-Collection Configuration (v2.9.14+ additions)

Per-collection attributes are persisted via PUT /v1/collection-config (REST), SetCollectionConfig (gRPC), the set_collection_config MCP tool, or the Admin Panel — not via env vars. The settings below extend what has been configurable since earlier versions.

Example — set a 20-revision cap:

curl -X PUT http://localhost:11023/v1/collection-config \ -H 'Content-Type: application/json' \ -d '{"collection":"blog","type":"default","maxRevisions":20}'

Curation Rules (v2.9.14+)

Curation is data, not configuration — rules live in a dedicated bolt bucket and are managed at runtime via /v1/curation (see API.md and SEARCH.md). No server-level flag controls the subsystem; it's always on and has zero overhead when no rules match an incoming query.

CLI Flags

YAML Config File

Pass via --config config.yaml or MDDB_CONFIG=config.yaml.

path: "mddb.db"
mode: "wr" # read, write, wr http: enabled: true addr: ":11023" grpc: enabled: true addr: ":11024" mcp: enabled: true addr: ":9000" stdio: false domain: "" http3: enabled: false addr: ":11443" auth: enabled: false jwtSecret: "" jwtExpiry: "24h" adminUsername: "admin" adminPassword: "" fts: stemmingEnabled: true synonymsEnabled: true compression: enabled: true smallThreshold: 1024 mediumThreshold: 10240 vector: defaultAlgorithm: "flat" bqRerankFactor: 10 parallelWorkers: 0 # 0 = auto (NumCPU, max 16) parallelMinSize: 2048 # min collection size for parallel search temporal: false spell: false mcp: apiKeyEnabled: false apiKeys: "" rateLimitEnabled: false rateLimitRequests: 100 rateLimitWindow: "60s" rateLimitBurst: 20 rateLimitBy: "ip" loggingEnabled: false

Total: 65+ environment variables across 17 categories, 10 CLI flags, full YAML config file support.