Persistent-state backend URL shared by every pvl-core subsystem that needs state. `memory://` is in-process and lost on restart; `file:///path` persists on one server; `redis://`, `dynamodb://` and `mongodb://` each need their matching extra. When unset, defaults to `file:///data/state` (the volume family Docker images mount), or to `memory://` — with a warning — on a host where that directory is not usable.Optional
Environment variable: MARKDOWN_VAULT_MCP_KV_STORE_URL
Comma-separated explicit tool names this instance exposes; every other tool is hidden from listings and cannot be invoked. Names matching no registered tool are inert. Mutually exclusive with `tools_deny`. Takes effect through `apply_tool_visibility`.Optional
Environment variable: MARKDOWN_VAULT_MCP_TOOLS_ALLOW
Comma-separated explicit tool names hidden from this instance (absent from listings, cannot be invoked). Names matching no registered tool are inert. Mutually exclusive with `tools_allow`. Takes effect through `apply_tool_visibility`.Optional
Environment variable: MARKDOWN_VAULT_MCP_TOOLS_DENY
Rename this server instance; defaults to the project name.Optional
Environment variable: MARKDOWN_VAULT_MCP_SERVER_NAME
Replaces the default MCP instructions text sent to clients.Optional
Environment variable: MARKDOWN_VAULT_MCP_INSTRUCTIONS
Log level for FastMCP internals and app loggers (DEBUG / INFO / WARNING / ERROR / CRITICAL). The -v CLI flag overrides to DEBUG.Optional
Environment variable: FASTMCP_LOG_LEVEL
Set false for plain or structured JSON log output.Optional
Environment variable: FASTMCP_ENABLE_RICH_LOGGING
Ollama server URL for the ollama embedding provider. Bare (not MARKDOWN_VAULT_MCP_-prefixed), matching the Ollama ecosystem convention.Optional
Environment variable: OLLAMA_HOST
OpenAI API key for the openai embedding provider, and the fallback key for the summarize tool when MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_API_KEY is unset. Bare (not MARKDOWN_VAULT_MCP_-prefixed), matching the OpenAI ecosystem convention.Required
Environment variable: OPENAI_API_KEY
Bare fallback for MARKDOWN_VAULT_MCP_OPENAI_BASE_URL (embeddings). For the summarize tool it only routes traffic when an API key already enables the feature; it never enables summarize by itself.Optional
Environment variable: OPENAI_BASE_URL
Bare fallback for MARKDOWN_VAULT_MCP_OPENAI_EMBEDDING_MODEL.Optional
Environment variable: OPENAI_EMBEDDING_MODEL
Maximum seconds an index-backed tool or resource waits for the FTS index to become queryable during a cold-start background build before raising IndexUnavailableError(reason="timeout"). Increase for large vaults.Optional
Environment variable: MARKDOWN_VAULT_MCP_BUILD_TIMEOUT_S
Maximum seconds an index-querying read tool waits for the IndexWriter to drain when called with wait_for_pending_writes=true. On timeout the tool answers from the current index and reports index_stale=true in the response _meta.Optional
Environment variable: MARKDOWN_VAULT_MCP_DRAIN_TIMEOUT_S
Path to the markdown vault directory. Required — the server refuses to start without it. Symbolic links inside the vault are followed on Python 3.13+.Optional
Environment variable: MARKDOWN_VAULT_MCP_SOURCE_DIR
Set to true to hide the write tools (write, edit, append, delete, rename, move_folder, fetch, git_sync, the okf_* tools, create_upload_link) and serve a search-only vault. git_sync also needs managed git mode; create_upload_link needs an HTTP transport.Optional
Environment variable: MARKDOWN_VAULT_MCP_READ_ONLY
Hide the MCP Apps UI tools (browse_vault, show_context) from the tool listing for clients that do not render MCP Apps panels.Optional
Environment variable: MARKDOWN_VAULT_MCP_DISABLE_APPS_UI
Path to the SQLite FTS5 index file; unset keeps the index in memory. Set it for persistence across restarts.Optional
Environment variable: MARKDOWN_VAULT_MCP_INDEX_PATH
Path to the change-tracking state file. Defaults to {SOURCE_DIR}/.markdown_vault_mcp/state.json.Optional
Environment variable: MARKDOWN_VAULT_MCP_STATE_PATH
Path to the numpy embeddings file; required to enable semantic search.Optional
Environment variable: MARKDOWN_VAULT_MCP_EMBEDDINGS_PATH
Comma-separated frontmatter fields promoted to the tag index for structured filtering. Changing it cold-rebuilds the index once on next startup; SEARCHABLE_FIELDS inherits this value when unset.Optional
Environment variable: MARKDOWN_VAULT_MCP_INDEXED_FIELDS
Comma-separated frontmatter fields required on every document; documents missing any are excluded from the index.Optional
Environment variable: MARKDOWN_VAULT_MCP_REQUIRED_FIELDS
Comma-separated glob patterns excluded from scanning, e.g. .obsidian/**,.trash/**.Optional
Environment variable: MARKDOWN_VAULT_MCP_EXCLUDE
Frontmatter field used as the document title (falls back to title, the first H1, then the filename). Changing it cold-rebuilds the index once on next startup.Optional
Environment variable: MARKDOWN_VAULT_MCP_TITLE_FIELD
Comma-separated frontmatter fields whose text values become keyword-searchable and enrich first-chunk embeddings. Inherits INDEXED_FIELDS when unset; the sentinel none means filterable but not searchable. Changing it cold-rebuilds the index and re-embeds once on next startup.Optional
Environment variable: MARKDOWN_VAULT_MCP_SEARCHABLE_FIELDS
Relative folder where note templates live (used by the create_from_template prompt).Optional
Environment variable: MARKDOWN_VAULT_MCP_TEMPLATES_FOLDER
Directory of .md prompt files that extend or override built-in prompts; a relative path is resolved against SOURCE_DIR.Optional
Environment variable: MARKDOWN_VAULT_MCP_PROMPTS_FOLDER
Filename of the per-folder conventions files surfaced to clients at write time (bare .md filename without glob characters). Set to none to disable folder conventions.Optional
Environment variable: MARKDOWN_VAULT_MCP_CONVENTIONS_FILE
OKF (Open Knowledge Format) read semantics. With auto (the default), read annotations switch on when the vault declares an OKF version in its root index.md. Use off to disable OKF semantics entirely, or on to force them for an undeclared vault. Annotations are read-only; write behavior is never affected.Optional
Environment variable: MARKDOWN_VAULT_MCP_OKF_MODE
OKF (Open Knowledge Format) enforced write layer. When true on an OKF-active vault, the server stamps generated provenance on each write and clears any verified attestation when a note's content changes. It also keeps each written folder's log.md and index.md current, and exposes the okf_verify tool. Requires OKF_MODE to be auto or on (a true value with OKF_MODE=off is a config error). Off by default.Optional
Environment variable: MARKDOWN_VAULT_MCP_OKF_WRITE
How the okf_verify tool attributes a human review. This applies only when OKF_WRITE is on, which gates the tool. With elicit (the default), okf_verify asks the human to confirm the review through an MCP elicitation and records the attestation only on an affirmative reply. It fails closed when the client cannot elicit or the human declines, so a model that holds the human's token cannot self-attest. Use trust-auth to attribute to the authenticated caller with no confirmation (safe only when the sole caller is a human-driven UI), or off to hide the tool so attestation happens through external tooling. A non-default value with OKF_WRITE off is a config error.Optional
Environment variable: MARKDOWN_VAULT_MCP_OKF_VERIFY
Comma-separated allowed attachment extensions without the dot (e.g. pdf,png,jpg); use * to allow every non-markdown file. Unset selects the built-in allowlist.Optional
Environment variable: MARKDOWN_VAULT_MCP_ATTACHMENT_EXTENSIONS
Maximum attachment size in MB returned by read / accepted by write; 0 disables the limit.Optional
Environment variable: MARKDOWN_VAULT_MCP_MAX_ATTACHMENT_SIZE_MB
Maximum bytes returned by a full-document read of a note; use `read(path, section=…)` for partial reads. 0 disables the limit.Optional
Environment variable: MARKDOWN_VAULT_MCP_MAX_NOTE_READ_BYTES
Maximum chunks returned per document in search results.Optional
Environment variable: MARKDOWN_VAULT_MCP_CHUNKS_PER_FILE
Width of the snippet window (words) in search results; 0 returns full chunk content.Optional
Environment variable: MARKDOWN_VAULT_MCP_SNIPPET_WORDS
Down-weights longer chunks in ranking: score / (1 + alpha * log(chunk_count)).Optional
Environment variable: MARKDOWN_VAULT_MCP_LENGTH_DOWNWEIGHT_ALPHA
Word cap per chunk; the adaptive chunker splits at deeper heading levels, then paragraph/word boundaries, to respect it. Match it to the embedding model's context. A reindex applies a new value.Optional
Environment variable: MARKDOWN_VAULT_MCP_MAX_CHUNK_WORDS
Character cap enforced alongside MAX_CHUNK_WORDS to bound token-dense chunks. Unset derives min(1500, model context * 2.8). Set a positive value for an exact cap, or -1 to scale with the model's full context (can exhaust memory on long-context models). A reindex applies a new value.Optional
Environment variable: MARKDOWN_VAULT_MCP_MAX_CHUNK_CHARS
Words of overlap between adjacent budget-split fragments of the same heading section (0 disables). A reindex applies a new value.Optional
Environment variable: MARKDOWN_VAULT_MCP_CHUNK_OVERLAP_WORDS
Folder-prefix score multipliers (`prefix:weight` pairs, comma-separated, weights > 0) applied to all search modes; the deepest matching prefix wins (sessions:0.5 demotes sessions/**).Optional
Environment variable: MARKDOWN_VAULT_MCP_FOLDER_WEIGHTS
Per-column BM25 weights (`column:weight` pairs, comma-separated, weights >= 0) for keyword ranking. Columns: path, title, folder, heading, content, summary.Optional
Environment variable: MARKDOWN_VAULT_MCP_FTS_WEIGHTS
Embedding provider: openai, ollama, or fastembed. Unset auto-detects from the environment.Optional
Environment variable: MARKDOWN_VAULT_MCP_EMBEDDING_PROVIDER
Ollama embedding model name.Optional
Environment variable: MARKDOWN_VAULT_MCP_OLLAMA_MODEL
Force Ollama to embed on CPU only.Optional
Environment variable: MARKDOWN_VAULT_MCP_OLLAMA_CPU_ONLY
OpenAI-compatible API base URL for embeddings; the bare OPENAI_BASE_URL is honoured as a fallback.Optional
Environment variable: MARKDOWN_VAULT_MCP_OPENAI_BASE_URL
OpenAI-compatible embedding model name; the bare OPENAI_EMBEDDING_MODEL is honoured as a fallback.Optional
Environment variable: MARKDOWN_VAULT_MCP_OPENAI_EMBEDDING_MODEL
FastEmbed model name.Optional
Environment variable: MARKDOWN_VAULT_MCP_FASTEMBED_MODEL
FastEmbed model cache directory (in Docker, stored under /data/state/fastembed).Optional
Environment variable: MARKDOWN_VAULT_MCP_FASTEMBED_CACHE_DIR
Enrich embedding input with the note title, chunk heading, and (first chunk) searchable-field values. Flipping it re-embeds the whole vault once on next startup.Optional
Environment variable: MARKDOWN_VAULT_MCP_EMBED_CONTEXT
Per-request wall-clock budget in seconds for a single embedding HTTP call (OpenAI/Ollama). The local FastEmbed backend runs in-process with no network call and ignores this. CPU-only or large-model workloads may need 60-120 s; raise this if batches time out.Optional
Environment variable: MARKDOWN_VAULT_MCP_EMBED_TIMEOUT_S
Number of chunks sent per embedding request. Smaller batches shorten each request (useful under a tight timeout on slow models) at the cost of more round-trips.Optional
Environment variable: MARKDOWN_VAULT_MCP_EMBEDDING_BATCH_SIZE
Token/password for HTTPS git auth; remotes must be HTTPS when set.Required
Environment variable: MARKDOWN_VAULT_MCP_GIT_TOKEN
HTTPS remote URL for managed git mode: the server clones into an empty SOURCE_DIR on startup (or validates an existing origin) and enables the pull loop, auto-commit, and deferred push.Optional
Environment variable: MARKDOWN_VAULT_MCP_GIT_REPO_URL
Username for HTTPS git auth prompts (x-access-token for GitHub, oauth2 for GitLab, the account name for Bitbucket).Optional
Environment variable: MARKDOWN_VAULT_MCP_GIT_USERNAME
Seconds between git fetch + fast-forward update attempts; 0 disables periodic pull.Optional
Environment variable: MARKDOWN_VAULT_MCP_GIT_PULL_INTERVAL_S
Seconds of write-idle time before pushing; 0 pushes only on shutdown.Optional
Environment variable: MARKDOWN_VAULT_MCP_GIT_PUSH_DELAY_S
Git committer name for auto-commits; set this in Docker where git config user.name is empty.Optional
Environment variable: MARKDOWN_VAULT_MCP_GIT_COMMIT_NAME
Git committer email for auto-commits.Optional
Environment variable: MARKDOWN_VAULT_MCP_GIT_COMMIT_EMAIL
OIDC claim key used as the commit author name (e.g. name); overrides GIT_COMMIT_NAME per request when an OIDC token is present.Optional
Environment variable: MARKDOWN_VAULT_MCP_GIT_COMMIT_NAME_CLAIM
OIDC claim key used as the commit author email (e.g. email); overrides GIT_COMMIT_EMAIL per request when an OIDC token is present.Optional
Environment variable: MARKDOWN_VAULT_MCP_GIT_COMMIT_EMAIL_CLAIM
Run git lfs pull on startup to fetch LFS-tracked attachments; set to false for repos without LFS.Optional
Environment variable: MARKDOWN_VAULT_MCP_GIT_LFS
Watch the vault for external filesystem changes; auto-disabled when git pull or the webhook is active. Requires the file-watcher extra.Optional
Environment variable: MARKDOWN_VAULT_MCP_FILE_WATCHER
Seconds of quiet after the last filesystem event before reindexing.Optional
Environment variable: MARKDOWN_VAULT_MCP_FILE_WATCHER_DEBOUNCE_S
Keep the non-recursive watch on the vault root; set false to register zero source-dir-rooted FSEvents streams (avoids repeated macOS access prompts on a home-rooted vault) at the cost of root-level files relying on scans.Optional
Environment variable: MARKDOWN_VAULT_MCP_FILE_WATCHER_ROOT_FLOOR
Shared secret for the GitHub push-event webhook; when set, mounts POST /github-webhook on HTTP/SSE transports to trigger an immediate pull + reindex on push events.Required
Environment variable: MARKDOWN_VAULT_MCP_GITHUB_WEBHOOK_SECRET
Summarization backend (only openai is recognised). Unset auto-detects: the backend activates when credentials or an explicit endpoint are present.Optional
Environment variable: MARKDOWN_VAULT_MCP_SUMMARIZE_PROVIDER
API key for the OpenAI-compatible summarize endpoint; the bare OPENAI_API_KEY is honoured as a fallback. Unset works for keyless local endpoints (Ollama).Required
Environment variable: MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_API_KEY
OpenAI-compatible endpoint base URL for the summarize tool; setting it enables the tool even without an API key. The bare OPENAI_BASE_URL routes traffic only when a key already enables the feature.Optional
Environment variable: MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_BASE_URL
Chat model id used for summaries.Optional
Environment variable: MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_MODEL
Upper bound on generated tokens per summarize call; on reasoning models this budget also covers internal reasoning tokens.Optional
Environment variable: MARKDOWN_VAULT_MCP_SUMMARIZE_MAX_TOKENS
Cap on the number of notes summarised in one call (subtree expansion truncates to this many).Optional
Environment variable: MARKDOWN_VAULT_MCP_SUMMARIZE_MAX_NOTES
Aggregate cap on note characters sent to the model in one call; excess is truncated with a flag on the result.Optional
Environment variable: MARKDOWN_VAULT_MCP_SUMMARIZE_MAX_INPUT_CHARS
Per-request wall-clock budget in seconds for a single summarize backend call; keep it below the MCP client's request timeout so the server-side error wins the race.Optional
Environment variable: MARKDOWN_VAULT_MCP_SUMMARIZE_TIMEOUT
Link lifetime in seconds when the caller requests no explicit TTL.Optional
Environment variable: MARKDOWN_VAULT_MCP_TRANSFER_TTL_DEFAULT_S
Ceiling in seconds a caller-requested link TTL is clamped to.Optional
Environment variable: MARKDOWN_VAULT_MCP_TRANSFER_TTL_MAX_S
Post-success grace window in seconds: a served token's TTL shrinks to this so a stalled transfer can retry within it.Optional
Environment variable: MARKDOWN_VAULT_MCP_TRANSFER_GRACE_TTL_S
Crashed-handler reclaim window in seconds for an in-flight reservation.Optional
Environment variable: MARKDOWN_VAULT_MCP_TRANSFER_LEASE_S
Maximum size in bytes of a single upload.Optional
Environment variable: MARKDOWN_VAULT_MCP_TRANSFER_MAX_UPLOAD_BYTES
Seconds a long-running tool call may run in the foreground before it is promoted to a background job and a job handle is returned instead.Optional
Environment variable: MARKDOWN_VAULT_MCP_JOBS_SOFT_DEADLINE_S
Seconds a background-job record (working or finished) is retained for polling before it expires from the store.Optional
Environment variable: MARKDOWN_VAULT_MCP_JOBS_RESULT_TTL_S
Maximum live background jobs per calling subject; further promotions are rejected until older records expire.Optional
Environment variable: MARKDOWN_VAULT_MCP_JOBS_MAX_PER_SUBJECT
Public base URL of the deployed server, e.g. `https://mcp.example.com`. Required for OIDC. Also the fallback source of the MCP Apps domain when `app_domain` is unset.Optional
Environment variable: MARKDOWN_VAULT_MCP_BASE_URL
Single shared bearer token; enables bearer auth unless `bearer_tokens_file` is set, which takes precedence.Required
Environment variable: MARKDOWN_VAULT_MCP_BEARER_TOKEN
OIDC discovery document URL, e.g. `https://auth.example.com/.well-known/openid-configuration`.Optional
Environment variable: MARKDOWN_VAULT_MCP_OIDC_CONFIG_URL
OIDC client identifier registered with the provider.Optional
Environment variable: MARKDOWN_VAULT_MCP_OIDC_CLIENT_ID
OIDC client secret registered with the provider.Required
Environment variable: MARKDOWN_VAULT_MCP_OIDC_CLIENT_SECRET
Expected `aud` claim; tokens issued for another audience are rejected.Optional
Environment variable: MARKDOWN_VAULT_MCP_OIDC_AUDIENCE
Scopes a caller must present, space- or comma-separated. Defaults to `openid` in oidc-proxy mode.Optional
Environment variable: MARKDOWN_VAULT_MCP_OIDC_REQUIRED_SCOPES
Scopes advertised to MCP clients in protected-resource metadata, space- or comma-separated. Overrides the default `openid offline_access`; `oidc_required_scopes` is always added on top. Set this when the registered client is not permitted `offline_access`, or to have clients request extra claim scopes (e.g. `groups`) without also requiring them in every token.Optional
Environment variable: MARKDOWN_VAULT_MCP_OIDC_ADVERTISED_SCOPES
Signing key for issued JWTs; used in oidc-proxy mode only. When unset, the key is derived deterministically from `oidc_client_secret`, so tokens survive a restart — but rotating that secret invalidates every issued token. Set this explicitly to decouple token validity from secret rotation. Generate with `openssl rand -hex 32`.Required
Environment variable: MARKDOWN_VAULT_MCP_OIDC_JWT_SIGNING_KEY
Validate the access token instead of the id token.Optional
Environment variable: MARKDOWN_VAULT_MCP_OIDC_VERIFY_ACCESS_TOKEN
MCP Apps iframe domain, used for CSP sandboxing. Overrides the host derived from `base_url`.Optional
Environment variable: MARKDOWN_VAULT_MCP_APP_DOMAIN
Explicit auth-mode override, accepting `remote` or `oidc-proxy` (case- and whitespace-insensitive). When unset the mode is auto-detected from which auth variables are set; the override exists because having all four OIDC variables set is ambiguous between those two modes. Other values are ignored with a warning.Optional
Environment variable: MARKDOWN_VAULT_MCP_AUTH_MODE
Path to a TOML file mapping bearer tokens to subjects; overrides the single-token `bearer_token` mode.Optional
Environment variable: MARKDOWN_VAULT_MCP_BEARER_TOKENS_FILE
Subject assigned to the single-token bearer mode; ignored when `bearer_tokens_file` is set, since mapped mode carries per-token subjects.Optional
Environment variable: MARKDOWN_VAULT_MCP_BEARER_DEFAULT_SUBJECT
Mount path for the MCP endpoint.Optional
Environment variable: MARKDOWN_VAULT_MCP_HTTP_PATH
Run the server process as this UID; the container entrypoint chowns writable paths to match.Optional
Environment variable: PUID
Run the server process as this GID; pair with PUID to match the owner of a mounted volume.Optional
Environment variable: PGID
