| PAPERLESS_MCP_KV_STORE_URL | No | 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. |
| PAPERLESS_MCP_TOOLS_ALLOW | No | 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`. |
| PAPERLESS_MCP_TOOLS_DENY | No | 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`. |
| PAPERLESS_MCP_SERVER_NAME | No | Rename this server instance; defaults to the project name. |
| PAPERLESS_MCP_INSTANCE_DESCRIPTION | No | Concise routing context that distinguishes this deployment's material or responsibility. |
| PAPERLESS_MCP_INSTRUCTIONS_EXTRA | No | Deployment-specific behavioral policy added to the generated MCP instructions. |
| PAPERLESS_MCP_INSTRUCTIONS | No | Legacy: replaces all generated MCP instructions (deprecated; use _INSTANCE_DESCRIPTION for routing and _INSTRUCTIONS_EXTRA for policy). |
| PAPERLESS_MCP_LOG_LEVEL | No | Log level for every logger in the process, FastMCP's included (DEBUG / INFO / WARNING / ERROR / CRITICAL). The -v CLI flag overrides to DEBUG. The unprefixed FASTMCP_LOG_LEVEL still works for one major version and logs a deprecation warning. |
| PAPERLESS_MCP_LOG_FORMAT | No | Log rendering. rich is one colour event key=value line per record, for a terminal; json is one JSON object per record, for a collector. Unset picks rich when stderr is a terminal and json everywhere else, so a container or journald gets JSON with no configuration. |
| PAPERLESS_MCP_PAPERLESS_URL | No | Base URL of the Paperless-NGX REST API, without a trailing slash. The server refuses to start without it. |
| PAPERLESS_MCP_API_TOKEN | No | Paperless service-account token used for outbound API requests. The server refuses to start without it. Secret. |
| PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS | No | Per-request HTTP timeout in seconds. |
| PAPERLESS_MCP_HTTP_RETRIES | No | Retries for idempotent requests after network errors or 5xx responses. |
| PAPERLESS_MCP_DEFAULT_PAGE_SIZE | No | Default page size for list tools, from 1 through 100. |
| PAPERLESS_MCP_PAPERLESS_PUBLIC_URL | No | Public Paperless UI URL for user-visible links; defaults to PAPERLESS_URL. |
| PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S | No | Link lifetime in seconds when the caller requests no explicit TTL. |
| PAPERLESS_MCP_TRANSFER_TTL_MAX_S | No | Ceiling in seconds a caller-requested link TTL is clamped to. |
| PAPERLESS_MCP_TRANSFER_GRACE_TTL_S | No | Post-success grace window in seconds: a served token's TTL shrinks to this so a stalled transfer can retry within it. |
| PAPERLESS_MCP_TRANSFER_LEASE_S | No | Crashed-handler reclaim window in seconds for an in-flight reservation. |
| PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES | No | Maximum size in bytes of a single upload. |
| PAPERLESS_MCP_SHUTDOWN_GRACE_S | No | Seconds SIGTERM may spend draining in-flight requests before the HTTP server exits. Keep it at or below the termination grace period the orchestrator allows. `0` drops in-flight requests immediately. |
| PAPERLESS_MCP_BASE_URL | No | Public base URL of the deployed server, for example `https://mcp.example.com`. Required for OIDC. Also the fallback source of the MCP Apps domain when `app_domain` is unset. |
| PAPERLESS_MCP_BEARER_TOKEN | No | Single shared bearer token; enables bearer auth unless `bearer_tokens_file` is set, which takes precedence. Secret. |
| PAPERLESS_MCP_OIDC_CONFIG_URL | No | OIDC discovery document URL, for example `https://auth.example.com/.well-known/openid-configuration`. |
| PAPERLESS_MCP_OIDC_CLIENT_ID | No | OIDC client identifier registered with the provider. |
| PAPERLESS_MCP_OIDC_CLIENT_SECRET | No | OIDC client secret registered with the provider. Secret. |
| PAPERLESS_MCP_OIDC_AUDIENCE | No | Expected `aud` claim; tokens issued for another audience are rejected. |
| PAPERLESS_MCP_OIDC_REQUIRED_SCOPES | No | Scopes a caller must present, space- or comma-separated. Defaults to `openid` in oidc-proxy mode. |
| PAPERLESS_MCP_OIDC_ADVERTISED_SCOPES | 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. |
| PAPERLESS_MCP_OIDC_JWT_SIGNING_KEY | 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`. Secret. |
| PAPERLESS_MCP_OIDC_VERIFY_ACCESS_TOKEN | No | Validate the access token instead of the id token. |
| PAPERLESS_MCP_KV_STORE_URL | No | 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. |
| PAPERLESS_MCP_APP_DOMAIN | No | MCP Apps iframe domain, used for CSP sandboxing. Overrides the host derived from `base_url`. |
| PAPERLESS_MCP_TOOLS_ALLOW | No | 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`. |
| PAPERLESS_MCP_TOOLS_DENY | No | 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`. |
| PAPERLESS_MCP_AUTH_MODE | 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. |
| PAPERLESS_MCP_BEARER_TOKENS_FILE | No | Path to a TOML file mapping bearer tokens to subjects; overrides the single-token `bearer_token` mode. |
| PAPERLESS_MCP_BEARER_DEFAULT_SUBJECT | No | Subject assigned to the single-token bearer mode; ignored when `bearer_tokens_file` is set, since mapped mode carries per-token subjects. |
| PAPERLESS_MCP_SERVER_NAME | No | Rename this server instance; defaults to the project name. |
| PAPERLESS_MCP_INSTANCE_DESCRIPTION | No | Concise routing context that distinguishes this deployment's material or responsibility. |
| PAPERLESS_MCP_INSTRUCTIONS_EXTRA | No | Deployment-specific behavioral policy added to the generated MCP instructions. |
| PAPERLESS_MCP_INSTRUCTIONS | No | Legacy: replaces all generated MCP instructions (deprecated; use _INSTANCE_DESCRIPTION for routing and _INSTRUCTIONS_EXTRA for policy). |
| PAPERLESS_MCP_HTTP_PATH | No | Mount path for the MCP endpoint; the health routes derive their prefix from it. |
| PAPERLESS_MCP_HEALTH_DETAIL | No | 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). |
| PUID | No | Run the server process as this UID; the container entrypoint reassigns ownership of writable paths to match. |
| PGID | No | Run the server process as this GID; pair with PUID to match the owner of a mounted volume. |
| PAPERLESS_MCP_LOG_LEVEL | No | Log level for every logger in the process, FastMCP's included (DEBUG / INFO / WARNING / ERROR / CRITICAL). The -v CLI flag overrides to DEBUG. The unprefixed FASTMCP_LOG_LEVEL still works for one major version and logs a deprecation warning. |
| PAPERLESS_MCP_LOG_FORMAT | No | Log rendering. rich is one colour event key=value line per record, for a terminal; json is one JSON object per record, for a collector. Unset picks rich when stderr is a terminal and json everywhere else, so a container or journald gets JSON with no configuration. |
| PAPERLESS_MCP_PAPERLESS_URL | No | Base URL of the Paperless-NGX REST API, without a trailing slash. The server refuses to start without it. |
| PAPERLESS_MCP_API_TOKEN | No | Paperless service-account token used for outbound API requests. The server refuses to start without it. Secret. |
| PAPERLESS_MCP_HTTP_TIMEOUT_SECONDS | No | Per-request HTTP timeout in seconds. |
| PAPERLESS_MCP_HTTP_RETRIES | No | Retries for idempotent requests after network errors or 5xx responses. |
| PAPERLESS_MCP_DEFAULT_PAGE_SIZE | No | Default page size for list tools, from 1 through 100. |
| PAPERLESS_MCP_PAPERLESS_PUBLIC_URL | No | Public Paperless UI URL for user-visible links; defaults to PAPERLESS_URL. |
| PAPERLESS_MCP_TRANSFER_TTL_DEFAULT_S | No | Link lifetime in seconds when the caller requests no explicit TTL. |
| PAPERLESS_MCP_TRANSFER_TTL_MAX_S | No | Ceiling in seconds a caller-requested link TTL is clamped to. |
| PAPERLESS_MCP_TRANSFER_GRACE_TTL_S | No | Post-success grace window in seconds: a served token's TTL shrinks to this so a stalled transfer can retry within it. |
| PAPERLESS_MCP_TRANSFER_LEASE_S | No | Crashed-handler reclaim window in seconds for an in-flight reservation. |
| PAPERLESS_MCP_TRANSFER_MAX_UPLOAD_BYTES | No | Maximum size in bytes of a single upload. |