Skip to content

Authentication

This guide covers how to protect your markdown-vault-mcp server with authentication. Choose the mode that fits your deployment.

Transport requirement

Authentication only works with HTTP transport (--transport http or sse). It has no effect with --transport stdio.

Auth modes

The server supports five authentication modes:

Mode When to use Configuration
Multi-auth Mixed clients (such as Claude web with OIDC and Claude Code with bearer token) on the same server Set both MARKDOWN_VAULT_MCP_BEARER_TOKEN and OIDC variables
Bearer token Simple deployments behind a VPN, Docker compose stacks, development Set MARKDOWN_VAULT_MCP_BEARER_TOKEN only
OIDC (remote) Production, recommended over oidc-proxy: local JWKS validation, no token re-validation Set MARKDOWN_VAULT_MCP_BASE_URL + MARKDOWN_VAULT_MCP_OIDC_CONFIG_URL only
OIDC (oidc-proxy) Production with user identity, SSO, multi-user access; backward-compatible mode Set all four OIDC variables (BASE_URL, OIDC_CONFIG_URL, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET)
No auth Local stdio usage, trusted networks Default (nothing to configure)

When both bearer token and OIDC are configured, the server accepts either credential: a valid bearer token or a valid OIDC session. This is useful when different clients require different authentication flows against the same vault instance.

Bearer token

The simplest way to protect your server. A single static token shared between server and clients.

Setup

  1. Generate a random token:

    openssl rand -hex 32

  2. Set the environment variable:

    MARKDOWN_VAULT_MCP_BEARER_TOKEN=your-generated-token

  3. Start the server with HTTP transport:

    markdown-vault-mcp serve --transport http --port 8000

Client usage

Clients must include the token in every request:

Authorization: Bearer your-generated-token

When to use bearer token

  • Deployments behind a VPN or firewall
  • Docker compose stacks where services communicate internally
  • Development and testing environments
  • Any scenario where full OIDC is overkill

See also: examples/bearer-auth.env for a ready-to-use example.

Mapped bearer tokens (multi-subject)

The bearer-token mode above shares one subject across every authenticated caller (by default the library's bearer-anon, override with MARKDOWN_VAULT_MCP_BEARER_DEFAULT_SUBJECT). For audit logs and authorization that distinguish callers, switch to mapped-token mode by pointing MARKDOWN_VAULT_MCP_BEARER_TOKENS_FILE at a TOML file:

# tokens.toml
[tokens]
"ghp_alice_xxxxxxxx" = "user:alice@example.com"
"sk_ci_yyyyyyyy"     = "service:ci-bot"

Each token resolves to a distinct subject string for downstream attribution. Subject strings are opaque: the <kind>:<id> convention (user:, service:, token:) is documentation only. When BEARER_TOKENS_FILE is set it overrides BEARER_TOKEN (a WARNING is logged if both are present). A missing or malformed file aborts startup with ConfigurationError rather than silently denying every request.

OIDC

Full OAuth 2.1 authentication using an external identity provider. Supports user login flows, SSO, and multi-user access control.

OIDC mode selection

The server supports two OIDC modes:

Mode How it works When to use
remote (recommended) Validates tokens locally via JWKS. No client credentials needed. Token refresh happens between client and IdP directly. Most deployments. Avoids the OIDCProxy double-validation session timeout.
oidc-proxy Acts as an OAuth proxy: exchanges codes for tokens, stores sessions, re-validates upstream tokens on every request. When your provider requires Dynamic Client Registration (DCR) emulation or you need the proxy's session management.

Set MARKDOWN_VAULT_MCP_AUTH_MODE to force a mode, or let the server auto-detect:

  • All four OIDC vars set (BASE_URL, OIDC_CONFIG_URL, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET) → oidc-proxy (backward compatible)
  • Only BASE_URL + OIDC_CONFIG_URL set → remote

Migrating from oidc-proxy to remote

Remove OIDC_CLIENT_ID and OIDC_CLIENT_SECRET from your env. The server will auto-detect remote mode. Or set AUTH_MODE=remote explicitly.

How it works (remote mode)

The server validates tokens locally using JWKS, with no upstream token calls after startup:

Client → IdP (authenticate + get JWT)
Client → markdown-vault-mcp (present JWT → validate via JWKS)

How it works (oidc-proxy mode)

The server proxies OIDC itself, with no external auth sidecar to deploy:

Client → markdown-vault-mcp → OIDC Provider
  1. Client connects to the server
  2. Server redirects to the OIDC provider for login
  3. Provider authenticates the user and returns a code
  4. Server exchanges the code for tokens
  5. Subsequent requests include the JWT

Required variables

Variable Description
MARKDOWN_VAULT_MCP_BASE_URL 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_OIDC_CONFIG_URL OIDC discovery document URL (https://auth.example.com/.well-known/openid-configuration).
MARKDOWN_VAULT_MCP_OIDC_CLIENT_ID OIDC client identifier registered with the provider.
MARKDOWN_VAULT_MCP_OIDC_CLIENT_SECRET OIDC client secret registered with the provider.

Optional variables

Variable Default Description
MARKDOWN_VAULT_MCP_OIDC_AUDIENCE (none) Expected aud claim; tokens issued for another audience are rejected.
MARKDOWN_VAULT_MCP_OIDC_REQUIRED_SCOPES openid 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 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 Signing key for issued JSON Web 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 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 Validate the access token instead of the id token.

JWT signing key and secret rotation

When MARKDOWN_VAULT_MCP_OIDC_JWT_SIGNING_KEY is unset, FastMCP derives the signing key from the OIDC client secret, so the key stays the same across restarts. Rotating the client secret changes the derived key and invalidates every token issued under the old one. Set an explicit key to decouple token validity from client-secret rotation:

openssl rand -hex 32

Long-running sessions

Current MCP clients do not reliably refresh tokens; see Known Limitations. Configure all token lifetimes (access, id, refresh) on your identity provider to cover a full workday (8 h or more). For simpler deployments, bearer token auth is unaffected by these limitations.

Provider guides

For step-by-step setup with specific providers:

For the full OIDC reference (env vars, Docker Compose, subpath deployments, architecture):

Troubleshooting

"invalid client" error

The client_id and/or redirect_uris in your OIDC provider config don't match the values in your .env file. Verify both sides match exactly.

Tokens invalidated after a client-secret rotation

You're missing MARKDOWN_VAULT_MCP_OIDC_JWT_SIGNING_KEY. Without it, FastMCP derives the signing key from the OIDC client secret, so rotating that secret changes the derived key and invalidates every token issued under the old one. Generate and set a stable key to decouple token validity from secret rotation:

openssl rand -hex 32

Auth has no effect

Authentication only works with HTTP transport. If you're using --transport stdio, auth is silently ignored. Switch to --transport http.

Bearer token not working

  • Verify the env var is set and non-empty (whitespace-only values are ignored)
  • Check that clients send Authorization: Bearer <token> (not Basic or other schemes)
  • If OIDC is also configured, multi-auth is active: both bearer and OIDC are accepted simultaneously

OIDC redirect fails

  • Verify BASE_URL matches your public URL exactly (including any subpath prefix)
  • For subpath deployments, see the subpath deployment guide: BASE_URL must include the prefix, HTTP_PATH must not
  • Check that redirect_uris in your provider config includes your callback URL (such as https://mcp.example.com/auth/callback)

Session drops after token expiry

Symptom: the MCP client works for a period (often ~1 hour), then starts returning 401 errors or stops responding. Restarting the client fixes it temporarily.

Root cause: this is almost always a token lifetime issue, not a server bug. Check three things:

  1. id_token lifetime (most common): When using verify_id_token mode (the default for Authelia), the server re-validates the upstream id_token on every request. If your provider's id_token lifetime is shorter than the access_token lifetime, the session dies at the id_token expiry, even though the access token is still valid. Authelia defaults id_token to 1 hour. Fix: set id_token lifetime to match access_token in your provider config.

  2. access_token lifetime: If both id_token and access_token are set correctly but sessions still drop, check that the provider's expires_in response matches your configured lifetime.

  3. No refresh token: See Known Limitations below. Current MCP clients cannot refresh tokens, so sessions are limited to the token lifetime.

Workaround: configure all token lifetimes on your identity provider to cover a full workday:

# Authelia example
lifespans:
  custom:
    mcp_long_lived:
      access_token: '8h'
      id_token: '8h'        # must match access_token for verify_id_token mode
      refresh_token: '30d'

See the Authelia provider guide for the full configuration.

Opaque access tokens (Authelia)

Authelia issues opaque (non-JWT) access tokens. This is handled automatically: the server verifies the id_token instead. No extra configuration needed. See the Authelia guide for details.

Known Limitations: MCP OAuth token refresh

Ecosystem-wide issue

The limitations below affect all OAuth-protected MCP servers, not just markdown-vault-mcp. They are caused by issues in the MCP client implementations (Claude Code, Claude.ai, Claude Desktop) and the MCP Python SDK. Check the linked tracking issues for current status.

The problem

MCP clients cannot maintain sessions beyond the token lifetime because token refresh does not work. When tokens expire, the session drops and requires manual re-authentication. This affects every provider: Authelia, Keycloak, Google, Slack, Notion, Atlassian, and others.

Why refresh doesn't work

Three independent issues prevent token refresh:

Layer Issue Impact
Claude Code Stores refresh tokens but never uses them (claude-code#21333) Refresh tokens are obtained and saved but never sent back to refresh expired access tokens
Claude Code Does not ask for offline_access on its own (claude-code#7744) Most OIDC providers issue no refresh token without this scope. The server advertises openid offline_access in its protected-resource metadata, so a client that requests the advertised set gets a refresh-capable grant; one that ignores the metadata still does not.
MCP Python SDK Token refresh deadlocks inside SSE streams (python-sdk#1326) Even with a valid refresh token, the SDK hangs when attempting refresh during an active stream

The server-side refresh architecture (FastMCP's OAuthProxy.exchange_refresh_token()) is correctly implemented and would work, but it requires the client to initiate the refresh, which none of the current clients do reliably.

What works today

Remote auth mode (AUTH_MODE=remote or auto-detected) avoids the double-validation problem entirely. The server validates tokens locally via JWKS and never stores or re-validates upstream tokens. This is the recommended mode for new deployments.

Bearer token auth is unaffected by all of the above. If your deployment allows it (such as Claude Code with env vars, or API clients), bearer tokens are the simplest and most reliable option.

Long token lifetimes are the only viable workaround for OIDC in oidc-proxy mode. Set all three lifetimes (access, id, refresh) to cover your typical session duration:

  • access_token: '8h': covers a workday
  • id_token: '8h': must match access_token when using verify_id_token mode (critical for Authelia)
  • refresh_token: '30d': ready for when clients support refresh
  • Permit offline_access for the registered client; the server advertises it by default, so a client that honours the advertised scopes requests it. Where the client may not hold that scope, narrow what the server advertises with MARKDOWN_VAULT_MCP_OIDC_ADVERTISED_SCOPES rather than letting the authorization request fail

Tracking

These upstream issues are actively tracked:

When these are resolved, OIDC sessions should persist indefinitely via automatic token refresh with no changes needed to markdown-vault-mcp.