Configuration¶
Markdown Vault MCP reads all configuration from environment variables. Domain
variables carry the MARKDOWN_VAULT_MCP_ prefix; a few third-party variables
(FASTMCP_*, PUID/PGID) keep their upstream names.
This page is the complete reference: every variable the server reads appears
in exactly one table below. One source generates these tables, .env.example
and the packaged env files, alongside the
configuration generator, so the four cannot
disagree. The README carries a hand-picked subset of these variables as its
quick entry point.
Server¶
Transport, identity, and tool visibility. MARKDOWN_VAULT_MCP_SERVER_NAME
identifies the deployment, MARKDOWN_VAULT_MCP_INSTANCE_DESCRIPTION
distinguishes its material or responsibility for routing, and
MARKDOWN_VAULT_MCP_INSTRUCTIONS_EXTRA supplies deployment-specific behavioral
policy. The legacy MARKDOWN_VAULT_MCP_INSTRUCTIONS replaces all generated text,
ignores both additive variables, and logs a deprecation warning at startup.
Generated guidance targets 1,536 UTF-16 units, reserving 512 units for normal operator routing and policy within Claude Code's known 2,048-unit limit. Crossing either threshold logs a warning; startup continues and the server does not truncate the instructions.
MARKDOWN_VAULT_MCP_TOOLS_ALLOW and MARKDOWN_VAULT_MCP_TOOLS_DENY trim which
tools an instance exposes. Hidden tools disappear from tools/list and are
rejected on tools/call; resources and prompts are unaffected. Setting both
variables, or setting one to a value with no names in it, is a startup error.
A name matching no registered tool is ignored, but an allowlist that matches
nothing logs a startup warning, since the instance then exposes zero tools.
See fastmcp-pvl-core's README for the full semantics.
MARKDOWN_VAULT_MCP_HEALTH_DETAIL decides how much the unauthenticated /health
and /health/ready bodies say, since anyone who can reach the port can read
them: status alone, the default standard with the server name, version and
a verdict per readiness check, or full with a redacted reason for each check
that raised. See Docker deployment for the
routes themselves.
| Variable | Default | Description |
|---|---|---|
MARKDOWN_VAULT_MCP_TRANSPORT |
stdio |
Transport the server speaks: stdio for local Claude Desktop/Code, http or sse for a network server. |
MARKDOWN_VAULT_MCP_HOST |
127.0.0.1 |
Interface the HTTP server binds to. |
MARKDOWN_VAULT_MCP_PORT |
8000 |
TCP port for the HTTP server. |
MARKDOWN_VAULT_MCP_BASE_URL |
(none) | Public base URL of the deployed server (https://mcp.example.com). Required for OIDC. Also the fallback source of the MCP Apps domain when app_domain is unset. |
MARKDOWN_VAULT_MCP_TOOLS_ALLOW |
(none) | 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. |
MARKDOWN_VAULT_MCP_TOOLS_DENY |
(none) | 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. |
MARKDOWN_VAULT_MCP_SERVER_NAME |
(none) | Rename this server instance; defaults to the project name. |
MARKDOWN_VAULT_MCP_INSTANCE_DESCRIPTION |
(none) | Concise routing context that distinguishes this deployment's material or responsibility. |
MARKDOWN_VAULT_MCP_INSTRUCTIONS_EXTRA |
(none) | Deployment-specific behavioral policy added to the generated MCP instructions. |
MARKDOWN_VAULT_MCP_INSTRUCTIONS |
(none) | Legacy: replaces all generated MCP instructions (deprecated; use _INSTANCE_DESCRIPTION for routing and _INSTRUCTIONS_EXTRA for policy). |
MARKDOWN_VAULT_MCP_HTTP_PATH |
/mcp |
Mount path for the MCP endpoint; the health routes derive their prefix from it. |
MARKDOWN_VAULT_MCP_HEALTH_DETAIL |
standard |
How much the unauthenticated /health and /health/ready bodies say: status, standard (adds name, version and per-check verdicts), or full (adds redacted reasons; trusted networks only). |
Authentication¶
Callers authenticate with a bearer token, with OIDC, or with both. OIDC
itself has two modes. remote validates tokens locally against the
provider's JWKS and needs only MARKDOWN_VAULT_MCP_BASE_URL and
MARKDOWN_VAULT_MCP_OIDC_CONFIG_URL. oidc-proxy runs the OAuth flow
itself and also needs MARKDOWN_VAULT_MCP_OIDC_CLIENT_ID and
MARKDOWN_VAULT_MCP_OIDC_CLIENT_SECRET, registered with the provider as a
confidential client whose redirect URI points at this server.
The Required column below marks the oidc-proxy set. Setting all four
selects that mode and omitting the two client credentials selects remote,
so MARKDOWN_VAULT_MCP_AUTH_MODE is the way to state the choice rather than
leave it to be inferred. With none of these set, the server starts and
serves unauthenticated. See the authentication guide
for setup, mapped multi-subject tokens, and troubleshooting.
| Variable | Default | Required | Description |
|---|---|---|---|
MARKDOWN_VAULT_MCP_BEARER_TOKEN |
(none) | No | Single shared bearer token; enables bearer auth unless bearer_tokens_file is set, which takes precedence. |
MARKDOWN_VAULT_MCP_OIDC_CONFIG_URL |
(none) | Yes | OIDC discovery document URL (https://auth.example.com/.well-known/openid-configuration). |
MARKDOWN_VAULT_MCP_OIDC_CLIENT_ID |
(none) | Yes | OIDC client identifier registered with the provider. |
MARKDOWN_VAULT_MCP_OIDC_CLIENT_SECRET |
(none) | Yes | OIDC client secret registered with the provider. |
MARKDOWN_VAULT_MCP_OIDC_AUDIENCE |
(none) | No | Expected aud claim; tokens issued for another audience are rejected. |
MARKDOWN_VAULT_MCP_OIDC_REQUIRED_SCOPES |
openid |
No | Scopes a caller must present, space- or comma-separated. Defaults to openid in oidc-proxy mode. |
MARKDOWN_VAULT_MCP_OIDC_ADVERTISED_SCOPES |
openid offline_access |
No | 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 (such as groups) without also requiring them in every token. |
MARKDOWN_VAULT_MCP_OIDC_JWT_SIGNING_KEY |
derived |
No | Signing key for issued tokens; used in oidc-proxy mode only. When unset, the key is derived deterministically from oidc_client_secret, so tokens survive a restart. Rotating that secret then invalidates every issued token. Set this explicitly to decouple token validity from secret rotation. Generate with openssl rand -hex 32. |
MARKDOWN_VAULT_MCP_OIDC_VERIFY_ACCESS_TOKEN |
false |
No | Validate the access token instead of the id token. |
MARKDOWN_VAULT_MCP_AUTH_MODE |
(none) | No | 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. |
MARKDOWN_VAULT_MCP_BEARER_TOKENS_FILE |
(none) | No | Path to a TOML file mapping bearer tokens to subjects; overrides the single-token bearer_token mode. |
MARKDOWN_VAULT_MCP_BEARER_DEFAULT_SUBJECT |
bearer-anon |
No | Subject assigned to the single-token bearer mode; ignored when bearer_tokens_file is set, since mapped mode carries per-token subjects. |
Persistence¶
One URL configures every stateful subsystem. A redis://
MARKDOWN_VAULT_MCP_KV_STORE_URL is also reused for background tasks when
MARKDOWN_VAULT_MCP_TASKS_URL is unset, so a single URL covers both.
| Variable | Default | Description |
|---|---|---|
MARKDOWN_VAULT_MCP_KV_STORE_URL |
file:///data/state |
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. |
MARKDOWN_VAULT_MCP_EVENT_STORE_URL |
(none) | Legacy state-backend override, used by build_event_store and build_kv_store only when kv_store_url is unset. It then backs every namespace, not just HTTP resumability. Prefer kv_store_url for new deployments. |
MARKDOWN_VAULT_MCP_TASKS_URL |
(none) | Background-task (Docket) backend URL: memory:// is in-process and lost on restart; redis:// is durable and multi-process. When unset, a redis:// kv_store_url is reused for tasks too; otherwise fastmcp's memory:// default applies. Only applies when task-enabled tools exist. Applied via configure_task_backend. |
Background tasks¶
Every Markdown Vault MCP instance wires a background-task backend at startup, so
a tool registered with task=True works with no extra setup.
MARKDOWN_VAULT_MCP_TASKS_URL (under Persistence above) picks the backend:
memory:// runs tasks in-process and loses them on restart; redis://... is
durable and shared across processes. With neither it nor a redis:// KV
store set, the backend falls back to memory://, which the server logs at
startup when running over HTTP. The queue name comes from the
MARKDOWN_VAULT_MCP prefix, so two servers sharing one Redis do not share a
queue.
Worker tuning stays on the native FASTMCP_DOCKET_* variables below. Set the
backend through MARKDOWN_VAULT_MCP_TASKS_URL rather than
FASTMCP_DOCKET_URL: the former wins when both are set, and the server warns
about the disagreement.
| Variable | Default | Description |
|---|---|---|
FASTMCP_DOCKET_CONCURRENCY |
10 |
Maximum background tasks this worker runs at once. |
FASTMCP_DOCKET_WORKER_NAME |
(none) | Identifies this worker in the queue; defaults to a generated name. |
FASTMCP_DOCKET_REDELIVERY_TIMEOUT |
300 |
Seconds before a task claimed by a worker that never finished is redelivered to another. |
FASTMCP_DOCKET_RECONNECTION_DELAY |
5 |
Seconds to wait before reconnecting after the queue connection drops. |
FASTMCP_DOCKET_MINIMUM_CHECK_INTERVAL |
0.05 |
Seconds between queue polls; lower cuts latency and raises idle load. |
MCP Apps¶
| Variable | Default | Description |
|---|---|---|
MARKDOWN_VAULT_MCP_APP_DOMAIN |
(none) | MCP Apps iframe domain, used for CSP sandboxing. Overrides the host derived from base_url. |
Logging¶
FASTMCP_ENABLE_RICH_LOGGING picks the shape of FastMCP's own log output,
the request-logging middleware included. Left on, Rich renders each record
with color, a time column and the source file that emitted it. Turned off, the
middleware emits one JSON object per record and the rest of FastMCP's loggers
emit LEVEL: message. This server's own markdown_vault_mcp.* lines are not
affected either way: the CLI attaches its own one-line handler to the root
logger.
The container image and the packaged systemd unit both default it to false,
because neither stream is a terminal. Rich falls back to 80 columns there, and
a structured record does not fit in what its own columns leave, so each record
wraps across three space-padded lines that neither docker logs nor a
collector reads back. docker logs -t and journalctl both carry a timestamp
per line, covering the column Rich stops printing. Both are ordinary
environment defaults: .env, the compose environment: block and
/etc/markdown-vault-mcp/env all override them. Turning Rich back on inside a
container wraps the records again unless COLUMNS is set too, which is what
Rich reads in preference to asking the terminal.
| Variable | Default | Description |
|---|---|---|
FASTMCP_LOG_LEVEL |
INFO |
Log level for FastMCP internals and app loggers (DEBUG / INFO / WARNING / ERROR / CRITICAL). The -v CLI flag overrides to DEBUG. |
FASTMCP_ENABLE_RICH_LOGGING |
true |
Rich color output for a terminal; false gives one plain or JSON line per record. Off in the container image and the systemd unit, since neither is a terminal and Rich wraps a structured record at its 80-column fallback. |
Container runtime¶
Read by the container entrypoint (Docker / Compose), not by the server process.
| Variable | Default | Description |
|---|---|---|
PUID |
1000 |
Run the server process as this UID; the container entrypoint reassigns ownership of writable paths to match. |
PGID |
1000 |
Run the server process as this GID; pair with PUID to match the owner of a mounted volume. |
Remote debugger¶
Development only; the image must be built with --build-arg DEBUG=true, and
the protocol is unauthenticated. See
remote debugging.
| Variable | Default | Description |
|---|---|---|
MARKDOWN_VAULT_MCP_DEBUG_PORT |
5678 |
debugpy listen port; the image must be built with --build-arg DEBUG=true. |
MARKDOWN_VAULT_MCP_DEBUG_WAIT |
false |
Block startup until a debugger attaches. |
Domain variables¶
Configuration is validated at startup
Invalid numeric ranges and incompatible settings fail startup with a
ConfigurationError naming the setting. The server does not silently
replace invalid values with defaults.
Write safety¶
MARKDOWN_VAULT_MCP_READ_ONLY=true hides every write-tagged tool. Writable
servers default to MARKDOWN_VAULT_MCP_WRITE_PROTECT_EXISTING=true.
Whole-file write operations (notes and attachments) and fetch operations
over an existing path require the matching if_match etag.
Targeted edit, append, delete, and rename
operations are unaffected, as are the server's generated OKF maintenance files.
Upload links have no if_match option. With protection enabled,
create_upload_link rejects existing destinations; the upload also fails if
the file appears before the bytes arrive. Use a new path, or set
MARKDOWN_VAULT_MCP_WRITE_PROTECT_EXISTING=false to allow blind overwrites.
See transfer links.
Write tools default to enabled
Since 4.0, MARKDOWN_VAULT_MCP_READ_ONLY defaults to false. An upgrade
from 3.x widens access unless the deployment explicitly sets
MARKDOWN_VAULT_MCP_READ_ONLY=true.
Upgrading from 4.x: overwrite protection is enabled
Set MARKDOWN_VAULT_MCP_WRITE_PROTECT_EXISTING=false explicitly if a
deployment must retain blind whole-file replacement. Otherwise, read the
file and pass its etag as if_match when replacing it, or use edit for
targeted changes. An empty setting uses the enabled default.
Direct Python construction with VaultSettings retains its library default,
write_protect_existing=False. Settings assembled from ProjectConfig use
the server default above.
Indexing and search¶
Persistent deployments normally put INDEX_PATH, EMBEDDINGS_PATH, and
STATE_PATH outside content folders. The file watcher excludes the directories
holding those files so index writes cannot trigger another scan; placing state
inside a content directory also prevents sibling content in that directory
from being watched.
INDEXED_FIELDS controls structured filters. SEARCHABLE_FIELDS defaults to
the same list and controls keyword-searchable frontmatter plus first-chunk
embedding context; set it to none to keep fields filterable but not searchable.
Changing either field triggers the required one-time index or embedding rebuild
on the next startup.
Ranking-only settings such as CHUNKS_PER_FILE, SNIPPET_WORDS, folder weights,
and FTS weights take effect without reindexing. Chunk-size and overlap settings
change the stored index and require reindex. Changing the embedding model or
an explicit character cap rejects the warm-start shortcut and rebuilds
automatically.
Embeddings and summarization¶
When EMBEDDING_PROVIDER is unset, provider detection tries OpenAI when
OPENAI_API_KEY exists, then a reachable Ollama server, then FastEmbed when its
package is installed. Voyage is never auto-selected. An explicitly selected
provider that cannot be configured fails startup; failed auto-detection logs a
warning and leaves semantic search disabled.
The optional summarize tool accepts any OpenAI-compatible chat-completions
endpoint. An API key enables hosted providers; setting
SUMMARIZE_OPENAI_BASE_URL enables keyless local endpoints such as Ollama. The
bare OPENAI_BASE_URL only routes summarization when a key already enables it.
Note content can leave your environment
The summarize tool sends referenced notes to its configured model
provider. Do not enable an external endpoint for vaults whose contents must
remain local.
Long summarize, reindex, and build_embeddings calls use protocol-native
background tasks when the client supports them. Other clients receive an inline
result before JOBS_SOFT_DEADLINE_S, or a job_id to poll with
get_job_result. A Redis tasks backend is durable and shared across workers;
the default memory backend is process-local and does not survive restarts.
Synchronization¶
Git has three modes: managed clone/pull/push with GIT_REPO_URL, commit-only
when the source directory is already a repository, and plain filesystem mode.
Token-authenticated remotes must use HTTPS. A GitHub webhook can trigger an
immediate pull and reindex in managed mode; periodic pull remains a fallback.
The filesystem watcher is enabled by default when neither periodic git pull nor
a live webhook owns change detection. Those mechanisms disable the watcher to
avoid scanning a partially updated checkout. A webhook credential counts only
where its endpoint exists: under --transport stdio there is no HTTP server to
receive a delivery, so the watcher keeps running rather than leaving that
deployment with no change detection at all. On macOS, set
FILE_WATCHER_ROOT_FLOOR=false for a home-rooted vault if FSEvents causes
repeated privacy prompts; root-level notes then rely on explicit scans.
Content and transfer¶
Folder convention files guide clients before writes. OKF read semantics can be
auto-detected from a root index.md; the separately gated OKF write layer adds
provenance, invalidates stale verification, and maintains log.md and
index.md. See the OKF guide for the trust and verification
model.
Attachments in hidden or excluded directories are never listed. Full note reads default to a 256 KiB limit and attachment reads to 1 MiB; section reads avoid loading an oversized note into the client context.
One-time transfer links require HTTP or SSE transport plus BASE_URL. Their
unguessable capability token is the authorization, and the persistent state
backend stores token state. The tools are absent on stdio.
For HTTP authentication, a static bearer token is the simplest option. OIDC configuration and deployment examples are covered in the authentication guide and OIDC deployment guide.
Boolean values accept true, 1, or yes case-insensitively. Ready-made
starting points live under examples/: obsidian-readonly.env,
obsidian-readwrite.env, obsidian-oidc.env, and ifcraftcorpus.env.
| Variable | Default | Required | Description |
|---|---|---|---|
OPENAI_BASE_URL |
(none) | No | 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. |
OPENAI_EMBEDDING_MODEL |
(none) | No | Bare fallback for MARKDOWN_VAULT_MCP_OPENAI_EMBEDDING_MODEL. |
MARKDOWN_VAULT_MCP_SOURCE_DIR |
/data/vault |
No | 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+. |
MARKDOWN_VAULT_MCP_READ_ONLY |
false |
No | 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. |
MARKDOWN_VAULT_MCP_WRITE_PROTECT_EXISTING |
true |
No | Refuse a write that would overwrite an existing file when no if_match etag is supplied. Deliberate replacement still works: read the file first, then pass if_match. Unaffected: edit, append, delete, rename. Set to false to allow blind overwrites. |
Embeddings¶
| Variable | Default | Required | Description |
|---|---|---|---|
OLLAMA_HOST |
http://localhost:11434 |
No | Ollama server URL for the ollama embedding provider. Bare (not MARKDOWN_VAULT_MCP_-prefixed), matching the Ollama ecosystem convention. |
OPENAI_API_KEY |
(none) | No | 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. |
VOYAGE_API_KEY |
(none) | No | Voyage AI API key for the voyage embedding provider. Bare (not MARKDOWN_VAULT_MCP_-prefixed), matching the OPENAI_API_KEY / OLLAMA_HOST convention. Setting it never auto-selects the provider; choose it explicitly with MARKDOWN_VAULT_MCP_EMBEDDING_PROVIDER=voyage. |
MARKDOWN_VAULT_MCP_EMBEDDING_PROVIDER |
(none) | No | Embedding provider: openai, voyage, ollama, or fastembed. Unset auto-detects from the environment (never voyage). Any OpenAI-compatible endpoint works with openai plus OPENAI_BASE_URL; see the embeddings guide. |
MARKDOWN_VAULT_MCP_OLLAMA_MODEL |
nomic-embed-text |
No | Ollama embedding model name. |
MARKDOWN_VAULT_MCP_OLLAMA_CPU_ONLY |
false |
No | Force Ollama to embed on CPU only. |
MARKDOWN_VAULT_MCP_VOYAGE_MODEL |
voyage-4 |
No | Voyage AI embedding model name. |
MARKDOWN_VAULT_MCP_OPENAI_BASE_URL |
https://api.openai.com/v1 |
No | OpenAI-compatible API base URL for embeddings; the bare OPENAI_BASE_URL is honoured as a fallback. |
MARKDOWN_VAULT_MCP_OPENAI_EMBEDDING_MODEL |
text-embedding-3-small |
No | OpenAI-compatible embedding model name; the bare OPENAI_EMBEDDING_MODEL is honoured as a fallback. |
MARKDOWN_VAULT_MCP_FASTEMBED_MODEL |
BAAI/bge-small-en-v1.5 |
No | FastEmbed model name. |
MARKDOWN_VAULT_MCP_FASTEMBED_CACHE_DIR |
(none) | No | FastEmbed model cache directory (in Docker, stored under /data/state/fastembed). |
MARKDOWN_VAULT_MCP_EMBED_CONTEXT |
false |
No | 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. |
MARKDOWN_VAULT_MCP_EMBED_TIMEOUT_S |
30.0 |
No | 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. |
MARKDOWN_VAULT_MCP_EMBEDDING_BATCH_SIZE |
4 |
No | 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. |
Timeouts¶
| Variable | Default | Required | Description |
|---|---|---|---|
MARKDOWN_VAULT_MCP_BUILD_TIMEOUT_S |
60 |
No | 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. |
MARKDOWN_VAULT_MCP_DRAIN_TIMEOUT_S |
60 |
No | 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. |
MCP Apps¶
| Variable | Default | Required | Description |
|---|---|---|---|
MARKDOWN_VAULT_MCP_DISABLE_APPS_UI |
false |
No | Hide the MCP Apps UI tools (browse_vault, show_context) from the tool listing for clients that do not render MCP Apps panels. |
Indexing¶
| Variable | Default | Required | Description |
|---|---|---|---|
MARKDOWN_VAULT_MCP_INDEX_PATH |
(none) | No | Path to the SQLite FTS5 index file; unset keeps the index in memory. Set it for persistence across restarts. |
MARKDOWN_VAULT_MCP_STATE_PATH |
(none) | No | Path to the change-tracking state file. Defaults to {SOURCE_DIR}/.markdown_vault_mcp/state.json. |
MARKDOWN_VAULT_MCP_EMBEDDINGS_PATH |
(none) | No | Path to the numpy embeddings file; required to enable semantic search. |
MARKDOWN_VAULT_MCP_INDEXED_FIELDS |
(none) | No | 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. |
MARKDOWN_VAULT_MCP_REQUIRED_FIELDS |
(none) | No | Comma-separated frontmatter fields required on every document; documents missing any are excluded from the index. |
MARKDOWN_VAULT_MCP_EXCLUDE |
(none) | No | Comma-separated glob patterns excluded from scanning (.obsidian/,.trash/). |
MARKDOWN_VAULT_MCP_TITLE_FIELD |
title |
No | 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. |
MARKDOWN_VAULT_MCP_SEARCHABLE_FIELDS |
(none) | No | 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. |
Content¶
| Variable | Default | Required | Description |
|---|---|---|---|
MARKDOWN_VAULT_MCP_TEMPLATES_FOLDER |
_templates |
No | Relative folder where note templates live (used by the create_from_template prompt). |
MARKDOWN_VAULT_MCP_PROMPTS_FOLDER |
(none) | No | Directory of .md prompt files that extend or override built-in prompts; a relative path is resolved against SOURCE_DIR. |
MARKDOWN_VAULT_MCP_CONVENTIONS_FILE |
_conventions.md |
No | 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. |
MARKDOWN_VAULT_MCP_OKF_MODE |
auto |
No | 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. |
MARKDOWN_VAULT_MCP_OKF_WRITE |
false |
No | 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. |
MARKDOWN_VAULT_MCP_OKF_VERIFY |
elicit |
No | 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, then records the attestation only on an affirmative reply. It fails closed when the client cannot elicit or the human declines, so a model holding the human's token cannot self-attest. Set trust-auth instead to attribute to a token's sub claim with no confirmation; it rejects static bearer credentials and other client-ID-only identities. This is safe only when the sole caller is a human-driven UI. Set off to hide the tool, leaving attestation to external tooling. A non-default value with OKF_WRITE off is a config error. |
MARKDOWN_VAULT_MCP_ATTACHMENT_EXTENSIONS |
(none) | No | Comma-separated allowed attachment extensions (such as pdf,png,jpg); case and a leading dot are ignored, so PDF and .pdf name the same type. Use * to allow every non-markdown file. Unset selects the built-in allowlist. A link whose target has a listed extension is not part of the link graph; changing the list rebuilds the index once. |
MARKDOWN_VAULT_MCP_MAX_ATTACHMENT_SIZE_MB |
1.0 |
No | Maximum attachment size in MB returned by read / accepted by write; 0 disables the limit. |
MARKDOWN_VAULT_MCP_MAX_NOTE_READ_BYTES |
262144 |
No | Maximum bytes returned by a full-document read of a note; use read(path, section=…) for partial reads. 0 disables the limit. |
Search tuning¶
| Variable | Default | Required | Description |
|---|---|---|---|
MARKDOWN_VAULT_MCP_DEFAULT_SEARCH_MODE |
auto |
No | Mode used when a search call omits 'mode': auto, keyword, semantic, or hybrid. The default 'auto' picks hybrid when embeddings are configured and keyword when they are not. Pin 'keyword' to keep unqualified searches off the embedding provider (each hybrid or semantic search embeds the query, which costs an API call on a metered provider). A configured semantic/hybrid default also degrades to keyword without embeddings, so no setting can make a vault unsearchable; an explicit mode= argument is never downgraded. |
MARKDOWN_VAULT_MCP_CHUNKS_PER_FILE |
2 |
No | Maximum chunks returned per document in search results. |
MARKDOWN_VAULT_MCP_SNIPPET_WORDS |
200 |
No | Width of the snippet window (words) in search results; 0 returns full chunk content. |
MARKDOWN_VAULT_MCP_LENGTH_DOWNWEIGHT_ALPHA |
0.25 |
No | Down-weights longer chunks in ranking: score / (1 + alpha * log(chunk_count)). |
MARKDOWN_VAULT_MCP_MAX_CHUNK_WORDS |
400 |
No | 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. |
MARKDOWN_VAULT_MCP_MAX_CHUNK_CHARS |
(none) | No | 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. |
MARKDOWN_VAULT_MCP_CHUNK_OVERLAP_WORDS |
40 |
No | Words of overlap between adjacent budget-split fragments of the same heading section (0 disables). A reindex applies a new value. |
MARKDOWN_VAULT_MCP_FOLDER_WEIGHTS |
(none) | No | 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/**). |
MARKDOWN_VAULT_MCP_FTS_WEIGHTS |
(none) | No | Per-column BM25 weights (column:weight pairs, comma-separated, weights >= 0) for keyword ranking. Columns: path, title, folder, heading, content, summary. |
Git sync¶
| Variable | Default | Required | Description |
|---|---|---|---|
MARKDOWN_VAULT_MCP_GIT_TOKEN |
(none) | No | Token/password for HTTPS git auth; remotes must be HTTPS when set. |
MARKDOWN_VAULT_MCP_GIT_REPO_URL |
(none) | No | 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. |
MARKDOWN_VAULT_MCP_GIT_USERNAME |
x-access-token |
No | Username for HTTPS git auth prompts (x-access-token for GitHub, oauth2 for GitLab, the account name for Bitbucket). |
MARKDOWN_VAULT_MCP_GIT_PULL_INTERVAL_S |
600 |
No | Seconds between git fetch + fast-forward update attempts; 0 disables periodic pull. |
MARKDOWN_VAULT_MCP_GIT_PUSH_DELAY_S |
30.0 |
No | Seconds of write-idle time before pushing; 0 pushes only on shutdown. |
MARKDOWN_VAULT_MCP_GIT_COMMIT_NAME |
markdown-vault-mcp |
No | Git committer name for auto-commits; set this in Docker where git config user.name is empty. |
MARKDOWN_VAULT_MCP_GIT_COMMIT_EMAIL |
noreply@markdown-vault-mcp |
No | Git committer email for auto-commits. |
MARKDOWN_VAULT_MCP_GIT_COMMIT_NAME_CLAIM |
(none) | No | OIDC claim key used as the commit author name (such as name); overrides GIT_COMMIT_NAME per request when an OIDC token is present. The claim is resolved when the tool call arrives and carried to the background commit, so it applies on every write. A configured claim the token does not carry is reported once at WARNING and the static identity is used. |
MARKDOWN_VAULT_MCP_GIT_COMMIT_EMAIL_CLAIM |
(none) | No | OIDC claim key used as the commit author email (such as email); overrides GIT_COMMIT_EMAIL per request when an OIDC token is present. Resolved and carried the same way as the name claim. |
MARKDOWN_VAULT_MCP_GIT_LFS |
true |
No | Run git lfs pull on startup to fetch LFS-tracked attachments; set to false for repos without LFS. |
Change detection¶
| Variable | Default | Required | Description |
|---|---|---|---|
MARKDOWN_VAULT_MCP_FILE_WATCHER |
true |
No | Watch the vault for external filesystem changes; auto-disabled when git pull is active or a webhook can deliver (HTTP/SSE transports only). Requires the file-watcher extra. |
MARKDOWN_VAULT_MCP_FILE_WATCHER_DEBOUNCE_S |
2.0 |
No | Seconds of quiet after the last filesystem event before reindexing. |
MARKDOWN_VAULT_MCP_FILE_WATCHER_ROOT_FLOOR |
true |
No | 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. |
MARKDOWN_VAULT_MCP_GITHUB_WEBHOOK_SECRET |
(none) | No | 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. |
MARKDOWN_VAULT_MCP_GITLAB_WEBHOOK_SIGNING_TOKEN |
(none) | No | Signing token for the GitLab push-event webhook (GitLab 19.0+); when set, mounts POST /gitlab-webhook on HTTP/SSE transports to trigger an immediate pull + reindex on push events. GitLab generates this value; copy the whsec_ token it shows under Generate signing token rather than inventing one. Deliveries are authenticated by HMAC-SHA256 over the webhook id, timestamp and body, and a delivery older than 5 minutes is rejected. |
MARKDOWN_VAULT_MCP_GITLAB_WEBHOOK_SECRET_TOKEN |
(none) | No | Secret token for the GitLab push-event webhook, GitLab's plain-text form and the only one below 19.0; also mounts POST /gitlab-webhook. It proves nothing about the body and cannot expire, so prefer the signing token where the GitLab version offers it. Setting both accepts either, which is how an existing webhook migrates. |
Summarize¶
| Variable | Default | Required | Description |
|---|---|---|---|
MARKDOWN_VAULT_MCP_SUMMARIZE_PROVIDER |
(none) | No | Summarization backend (only openai is recognised). Unset auto-detects: the backend activates when credentials or an explicit endpoint are present. |
MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_API_KEY |
(none) | No | 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). |
MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_BASE_URL |
(none) | No | 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. |
MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_MODEL |
gpt-5-mini |
No | Chat model id used for summaries. |
MARKDOWN_VAULT_MCP_SUMMARIZE_MAX_TOKENS |
8192 |
No | Upper bound on generated tokens per summarize call; on reasoning models this budget also covers internal reasoning tokens. |
MARKDOWN_VAULT_MCP_SUMMARIZE_MAX_NOTES |
50 |
No | Cap on the number of notes summarised in one call (subtree expansion truncates to this many). |
MARKDOWN_VAULT_MCP_SUMMARIZE_MAX_INPUT_CHARS |
200000 |
No | Aggregate cap on note characters sent to the model in one call; excess is truncated with a flag on the result. |
MARKDOWN_VAULT_MCP_SUMMARIZE_TIMEOUT |
120.0 |
No | 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. |
Transfer¶
| Variable | Default | Required | Description |
|---|---|---|---|
MARKDOWN_VAULT_MCP_TRANSFER_TTL_DEFAULT_S |
3600.0 |
No | Link lifetime in seconds when the caller requests no explicit TTL. |
MARKDOWN_VAULT_MCP_TRANSFER_TTL_MAX_S |
86400.0 |
No | Ceiling in seconds a caller-requested link TTL is clamped to. |
MARKDOWN_VAULT_MCP_TRANSFER_GRACE_TTL_S |
60.0 |
No | Post-success grace window in seconds: a served token's TTL shrinks to this so a stalled transfer can retry within it. |
MARKDOWN_VAULT_MCP_TRANSFER_LEASE_S |
60.0 |
No | Crashed-handler reclaim window in seconds for an in-flight reservation. |
MARKDOWN_VAULT_MCP_TRANSFER_MAX_UPLOAD_BYTES |
104857600 |
No | Maximum size in bytes of a single upload. |
Jobs¶
| Variable | Default | Required | Description |
|---|---|---|---|
MARKDOWN_VAULT_MCP_JOBS_SOFT_DEADLINE_S |
25.0 |
No | 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. |
MARKDOWN_VAULT_MCP_JOBS_RESULT_TTL_S |
3600.0 |
No | Seconds a background-job record (working or finished) is retained for polling before it expires from the store. |
MARKDOWN_VAULT_MCP_JOBS_MAX_PER_SUBJECT |
256 |
No | Maximum live background jobs per calling subject; further promotions are rejected until older records expire. |