Skip to content

Configuration

Environment

Variable Default Meaning
MCP_BASE_URL required Public URL of the proxy; also the OAuth issuer (https, or http only for localhost)
MCP_OAUTH_SECRET required Encrypts the stored logins in /data; changing it logs every client out
MCP_PROXY_CONFIG /config/proxy.yaml The config file
MCP_PORT 8081 Port the proxy listens on inside the container
LOG_LEVEL INFO Python log level
any other Referenced from the config file as ${NAME}, for secrets such as the user list

A missing or invalid setting stops the container at startup with a message naming it.

The config file

${NAME} is replaced from the environment when the file is loaded; a name that isn't set is an error. {name} placeholders are filled per login or per request from the variables below. {{ and }} are literal braces.

Key Default Meaning
service_name required Shown on the login form
upstream required The MCP server's full URL, e.g. http://trilium:8080/mcp; the query string of each request is kept
instructions none Added to the server's initialize result as instructions
fields required The login form: a list of {name, label, type, required, autocomplete, hint}; type is text, password or email
login required Exactly one of users, upstream or exchange (below)
messages none For exchange: an error code from the login answer → the text shown on the form
revoke none A request sent when a client revokes its login: {method, url, headers, json}
static_tokens off A variable name: a raw Authorization header (with or without Bearer) is accepted as that variable and passed on; the server judges it. Not allowed with users
vars none Derived variables: {name: {base64: "<template>"}}
upstream_headers none Headers added to each forwarded request, e.g. {Authorization: "Basic {basic}"}. The client's own Authorization is never forwarded
health none A URL /health checks; without it /health only says the proxy runs
token_prefix mlpx_ Prefix of the proxy's OAuth tokens
store_salt mcp-login-proxy-oauth Salt for the store's encryption key

Text fields are trimmed before they're used; password fields are passed exactly as typed.

login.users

A fixed list: name:hash entries separated by spaces or newlines, the hashes argon2id (mcp-login-proxy hash makes one). The form must have a user and a password field. The login only keeps {user}, never the password, and static_tokens is refused: the server behind it has no login, so a raw token would let anyone in.

login.upstream

upstream: {}. The form's values are rendered into upstream_headers and tried with one initialize request to upstream; any 2xx answer accepts the login. The login keeps the form's values that upstream_headers, vars and revoke use.

login.exchange

Key Meaning
request {method, url, headers, json} with the form's fields as placeholders. In json, a value that renders empty is left out
token The JSON field of the answer that holds the token
variable The variable it becomes, default token
error The JSON field of a refusal, looked up in messages; otherwise the form shows the HTTP status

Data volume

Mount a volume at /data. It holds the OAuth store (registered clients, tokens and each login's variables), encrypted with a key derived from MCP_OAUTH_SECRET and store_salt. Without the volume, every container restart logs all clients out.

Endpoints

Path What
/mcp The MCP server, behind the login
/health {"status": "ok"}, plus "upstream": "ok" \| "unreachable" with health set; no login needed
/.well-known/…, /authorize, /token, /register, /revoke and the login page The OAuth endpoints MCP clients find and use on their own

Moving from trilium-mcp-proxy

Mount docs/examples/trilium.yaml with TRILIUM_URL set, move MCP_INSTRUCTIONS into instructions, keep MCP_BASE_URL, MCP_OAUTH_SECRET and the /data volume. Its token_prefix, store_salt and variable are trilium-mcp-proxy's, so every existing login keeps working.